Issuing an Advisory

## An advisory is data before it is prose When you publish a security advisory for a library you maintain, almost nobody reads it. What reads it is tooling: an ecosystem advisory database ingests your entry, and a consumer's dependency check compares the versions it resolved against your ranges. If the structured part is wrong or missing, the prose is decoration - the consumers who needed the alert never get one, and consumers who did not need it get woken at 3am. So the real question is: what does a machine need in order to decide whether one installed version is affected? Four answers - identity, boundaries, per-line coverage, and the remedy. ## Identity: which package, in which ecosystem A package name alone is ambiguous. The same string exists in several registries, and forks and renames multiply it. The advisory must bind the flaw to an ecosystem plus a name - ideally a package URL (purl) such as `pkg:nuget/Example.Auth`, which encodes type, namespace and name in one string a resolver can compare against what it actually installed. If your project ships under more than one coordinate - a scoped and an unscoped name, a module path that changed at a major version, a copy vendored under a different name - each coordinate needs its own entry. Tooling matches the coordinate it resolved; a coordinate you did not list is a consumer you did not alert. ## Boundaries: introduced and fixed, as a half-open interval The affected set is expressed as a range with events. The common form is an `introduced` version and a `fixed` version, and the interval is half-open: the introduced version IS affected, the fixed version is NOT. `introduced: 0` means from the first release ever published. Where a line was never fixed you can bound it with a last-affected version instead. Where an ecosystem's versions cannot be ordered reliably, advisory formats let you enumerate affected versions explicitly rather than describe a range. Two details bite people. First, comparison uses the ecosystem's version ordering, not string comparison: `1.10.0` is greater than `1.9.0` numerically and smaller lexically, and prerelease precedence, epochs and normalisation rules differ per ecosystem - so declare which ordering applies (SemVer where the ecosystem is SemVer, the ecosystem's own ordering otherwise). Second, `introduced` is a claim about when the vulnerable code appeared, which is usually not the first release; reaching for zero out of caution condemns versions that never carried the bug. ## Per-line coverage: one range per maintained branch If you maintain 1.x and 2.x and backported the fix, there are two first-fixed versions and one range cannot express that. A single range from 0 to 2.3.1 marks every 1.x release affected including the patched 1.9.4 - every consumer on the fixed 1.x build gets a false alert and learns to ignore you. A single range starting at 2.0.0 leaves every 1.x consumer silent and exposed. The correct shape is one affected entry per maintained line, each with its own introduced and fixed events. A line you have decided not to patch still belongs in the advisory: mark it affected with no fixed version and say in the text that the remedy is moving to a supported line. Which lines get a backport is a release decision; what the advisory owes you is that every line's status is stated, including the ones with no good answer. ## The remedy and the rest Beyond ranges, an advisory carries: a summary and detail text a human can act on; the severity published as a vector string rather than a bare number, so a reader can see which assumption drives it; references to the fix commit or release notes; the identifier plus any aliases, so a consumer who already has this flaw under a different ID does not act on it twice; and credit for the reporter, which costs nothing and is how you keep getting reports. Timing matters as much as content. An advisory naming 2.3.1 before 2.3.1 is downloadable tells attackers exactly where to look and leaves defenders nothing to do. ## When you get it wrong You will. Ranges get corrected constantly - the flaw predates the version you named, or a branch was missed, or a coordinate was forgotten. Advisory formats carry a modified timestamp precisely because entries are living documents. Correct the entry in place; do not open a second one. A duplicate splits the ecosystem's view of one flaw and both copies end up half-trusted. The habit worth building: before publishing, take your own draft and evaluate it against two real installed versions - one you believe is affected, one you believe is not - and confirm the range actually says what you meant.