Vulnerability range events¶

Definition¶

Vulnerability range events are a way of stating which versions of a package a vulnerability affects as an ordered timeline of status changes — introduced, fixed, last-affected, limit — evaluated against a candidate version by a published algorithm, so that answering whether a particular build is vulnerable becomes a mechanical computation over the advisory instead of an interpretation of prose.

Explanation¶

The mechanism is a small state machine over sorted events. Each affected package carries ranges; each range declares a type that fixes how its version strings are ordered and therefore compared — semantic-version precedence, arbitrary ecosystem-specific strings that only that ecosystem knows how to order, or git commit hashes where "earlier" means "is an ancestor of" and evaluation consequently requires a copy of the repository. Every event object carries exactly one key, every range needs at least one introduced event, and the special introduced value zero sorts before all versions. A consumer walks the events in order flipping a vulnerable flag on and off, which is what lets one range express several disjoint affected windows rather than needing one range each. Two design consequences matter more than the syntax. First, a fixed event and a last-affected event are not interchangeable: last-affected records a ceiling known at disclosure time on the assumption that the next release will carry the fix, so anything above it is presumed safe and a false negative is possible, whereas fixed names the version that actually contains the fix and needs no such assumption — the standard's strong preference for fixed is a preference for a data model that errs toward false positives. Second, the same asymmetry governs git ranges: a range using fixed events must enumerate every cherry-picked fix commit across every branch or unrelated branches match falsely, while the limit alternative restricts matching to commits reachable from a named point and risks missing affected branches entirely. Because ecosystem-typed and git-typed ranges cannot be evaluated by an ecosystem-independent processor, an explicitly enumerated version list is expected alongside them, and only semantic-version ranges stand on their own. The source is the OSV schema specification itself, an explicitly stable standard evolved backwards-compatibly, whose consumers are instructed to process newer minor versions by ignoring fields they do not recognize.

Key Properties¶

Ranges are event timelines, so a single range can express several disjoint affected windows
The range type fixes version ordering: semantic-version precedence, opaque ecosystem strings, or git ancestry
A fixed event is preferred over last-affected, which presumes the next release fixes it and so admits false negatives
Git ranges must enumerate every cherry-picked fix commit, or use limit and accept the opposite error
Ecosystem and git ranges need an enumerated version list; only semantic-version ranges are self-sufficient

Relationships¶

OSV format — is the interchange format this data model sits inside — that concept covers why the format exists and who adopted it, while this is the part a producer or scanner author has to implement correctly for the adoption to mean anything
CycloneDX object model — names what components are present in a build, where this decides which of them a given advisory actually hits, so inventory and applicability are separate problems that meet at the version string

Applications¶

Writing advisories for a project so that scanners can match them without ecosystem-specific interpretation; implementing or auditing a dependency scanner's version-matching logic; deciding, when publishing, whether an advisory can name a fixed version or must settle for a last-affected ceiling.

Sources¶

https://ossf.github.io/osv-schema/