Vulnlog
Vulnlog is a declarative format and a set of tools for describing how vulnerabilities affect your software and what you plan to do about them. You record your assessment once, in a Vulnlog file in your Git repository. Vulnlog generates what your scanners, your team, and your customers need from it.
Vulnlog doesn’t scan your software, and it doesn’t analyse vulnerabilities for you. It works alongside your scanners and vulnerability management platforms and doesn’t replace them.
The problem
Vulnerability reports reach your software from many sources: security scanners, security researchers, penetration tests and audits, and customers who scan your product. For each report, you analyse whether the vulnerability affects your software and, if it does, how severely.
Many vulnerabilities don’t affect your software, but your scanners keep reporting them. Others do affect it, and you can’t always fix them and release straight away. Until you do, your team needs to know which releases are affected, and your customers want to know what you plan to do.
Who Vulnlog is for
Vulnlog is for teams that ship software in releases and have to answer for the vulnerabilities in it.
-
Developers and security engineers who analyse scanner findings. They write each analysis once, next to the code, and stop maintaining an ignore file for every scanner.
-
Release managers and product managers who need to know what affects a release. They read the impact report and the release notes, and they don’t need to know YAML.
-
Support engineers who answer customers' questions about a vulnerability. They find the team’s verdict and its reasoning in the impact report.
Vulnlog suits projects with planned releases best, where a vulnerability can stay in a release for weeks or months. If you fix and release continuously, you’ll use less of it. See Where Vulnlog fits.
Why use Vulnlog
-
You don’t need a server, a cloud service, an account, or a subscription. Vulnlog is a YAML file and tools you run from the command line, in a Docker container, with the Gradle plugin, or in GitHub Actions.
-
You analyse a vulnerability next to the code it affects. You don’t switch between your code and a wiki, a spreadsheet, an issue tracker, or a vulnerability management platform.
-
Because the Vulnlog file is in Git, you change an analysis in a pull request, and another person can review it. Your conclusions can change as you learn more about a vulnerability. Git shows what changed, who changed it, and when.
-
New team members can read earlier analyses and build on them.
-
Vulnlog generates suppression files from the current Vulnlog file. When you fix a vulnerability or a suppression expires, the next generated file no longer contains it, so outdated suppressions don’t hide new risks.
-
Your analysis doesn’t depend on a scanner or a vendor. When you switch to another scanner or add one, you note the new scanner on the vulnerabilities it flags, and Vulnlog writes its suppression file.
-
Vulnlog is free and open source under the Apache 2.0 licence. If a feature you need is missing, you can propose it and contribute it.
How it works
Declare impact and plans
You record each vulnerability as an entry in the Vulnlog file. An entry says which releases are affected, your verdict, the reasoning behind it, and what you plan to do. If the same vulnerability reaches you from several sources, it’s still one entry, with a report for each source. In this example, a scanner and a customer reported the same vulnerability:
- 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
When the fix ships, you add a resolution with the release that contains the fix.
Generate what others need
You don’t write suppression files or reports yourself. From the entries in your Vulnlog file, Vulnlog generates:
-
Suppression files that your scanners read, in their native format or as a generic list
-
An impact report that shows which releases are affected and how severely
-
Release notes that list the vulnerabilities a release fixes
-
OpenVEX documents that tell your customers' tools whether a release is affected (incubating)
For a list of scanners with a native format, see Supported scanners.
Get started
Install Vulnlog and follow Triage your first finding. If you don’t maintain the Vulnlog file yourself, start with Read the impact report or Answer a vulnerability inquiry.
The documentation has four parts:
-
Tutorials teach you Vulnlog step by step with one example project, Acme Shop. After the first one, continue with Track a vulnerability to its fix.
-
How-to guides each solve one task, for example Triage a new scanner finding or Run in CI pipelines.
-
The reference describes every field, command, and option. Start with File format or Vulnlog CLI.
-
The explanation pages give the reasons behind the design. Start with The data model.
If you have questions, ask in GitHub Discussions.