The data model
When you open a Vulnlog file, you see a project, a list of releases, and a list of vulnerability entries.
Releases and tags
The file lists the releases of your software, oldest first.
Each entry names the releases the vulnerability affects, and a resolution names the release that contains the fix.
The order matters because a question about one release, such as what affected 4.2.0 in the Acme Shop example, also covers every release listed before it.
Vulnlog takes the order from the list alone.
It doesn’t compare version numbers or published_at dates, so any version scheme works, and a release that hasn’t shipped yet already has its place.
See Vulnerability states.
Tags are labels you define for parts of your software, such as backend, frontend, worker, and container in Acme Shop.
You put them on entries and on the package URLs (PURLs) of each release.
They let you generate a report or a suppression file for one part of the software only.
Tags also decide what goes into OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability.
A statement for an entry names only the release PURLs that share a tag with the entry, and an entry without tags gets no statement.
The three parts of an entry
Every entry is about one vulnerability, identified by its id and any aliases.
A file has one entry per vulnerability, and that entry has one verdict for all the releases and parts of your software it lists.
When a vulnerability affects one part but not another, the verdict is affected, and the analysis says which part.
If you tag the entry with that part only, a report filtered by the tag of another part leaves the entry out.
So do the OpenVEX statements for the release PURLs of that other part.
Release lines that need different verdicts get their own files.
See Support several release lines.
Around that identity, an entry holds three kinds of information that change at different times and for different reasons.
What reached you
The reports say who told you about the vulnerability and when.
A scanner finding is a report.
So is a customer’s question or an audit result.
When a second source reports the same vulnerability, it gets a report in the existing entry, and the file keeps one entry for the vulnerability.
Log4Shell in Acme Shop has two reports, one from Grype and one from a customer support request.
Reports also carry what belongs to one source only. A scanner might use its own identifier for the vulnerability, and you might want to silence one scanner, for a limited time or permanently. Both are set on that scanner’s report, so they don’t affect the others.
What you concluded
Your judgement is the analysis (the reasoning in your own words), the verdict, and the fields that go with the verdict.
A not affected verdict needs a justification, such as vulnerable code not in execute path for Text4Shell.
An affected verdict needs your severity, and can state a disposition: you plan to fix it (will fix), or you accept the risk (wont fix).
The judgement is the part you’re most likely to revise, and each revision replaces the old judgement in the file. See Why your analysis lives in Git.
Why the separation matters
Each output reads the part of the entry it needs.
Suppression files follow your judgement, so a not affected vulnerability stops showing up in your scanners.
They also follow your action: once an entry has a resolution, it’s left out of suppression files.
See Vulnlog and your scanner.
The impact report combines judgement and action into a state, such as open or resolved.
See Vulnerability states.
The reports in an entry don’t change the state at all, so adding a second scanner never reopens a verdict you’ve already recorded.
The file also leaves out what other sources already know, such as CVSS scores and advisory texts. What Vulnlog leaves out explains why.