A maintainer should publish a structured advisory that names the package precisely, gives affected version ranges and the first fixed version, describes workarounds, and is repeated in the release notes. Clear ranges let downstream teams match the advisory to their SBOMs in minutes instead of hours.
What downstream teams need
Teams doing an SBOM-driven response search for a component and compare versions. The more precise your advisory, the faster that is. The OSV schema shows the fields consumers' tooling expects: a package with ecosystem and name, ranges with introduced and fixed events, and optionally an explicit list of affected versions. The schema recommends fixed over last_affected, and notes that last_affected can cause false negatives if a fix later lands in a higher version.
A maintainer's checklist
- Name the package exactly: ecosystem, any namespace, and package name. If your project publishes several packages, list each one separately.
- State where the problem started with an introduced version. If you do not know, say so rather than guessing zero.
- State the first fixed version for every supported release line.
- Describe a workaround if one exists, and say when it is not enough.
- Say plainly which versions are unsupported and will not get a fix.
- Link the advisory from the release notes, the repository security page and the changelog.
- Credit reporters if they agreed to it.
- Publish in the structured form your ecosystem's advisory database accepts, so scanners pick it up.
Version range pitfalls
| Pitfall | Effect on downstream |
|---|---|
| Range stated as "older versions" | Teams cannot match it to an SBOM |
| Only the latest line has a fix | Teams on older lines do not know their path |
| Fixed version missing | Teams cannot tell when they are safe |
| Different names in text and metadata | Scanner matches fail |
What to say about exploitability
You know your code best. If only certain features or configurations are vulnerable, say so, since it lets downstream teams judge reachability for their own use. The CISA minimum requirements for VEX show how suppliers and third parties convey status such as not affected or fixed, but a maintainer does not have to produce VEX to help. A precise advisory is enough for most teams.
Updates
If the advisory changes, change it in place with a visible revision note and date. Downstream teams may have copied the first version into tickets, so the update should be easy to spot.
Burden and boundaries
Maintainers volunteer their time. Do what is realistic: a clear advisory and a fixed release are a large contribution on their own. Downstream users who depend on your work can help by testing fixes and reporting versions precisely.
Quick check
Do I need to publish a VEX document?
No. A precise advisory with ranges and a fixed version serves most downstream teams.
What if I do not know when the bug was introduced?
Say that it is unknown and list the oldest version you tested, instead of claiming all versions.
Safeguard's dependency scanning and zero-day discovery help consuming teams pick up advisories like these and act on them.
Sources
Last reviewed: 19 October 2026.
