# Security Advisory Timeline

> Disclosures, affected ranges, fixes and withdrawals for a package on one timeline, with time-to-fix. Merges every OSV.dev advisory for a package (npm, PyPI, Go, crates.io, Maven, RubyGems, Packagist, NuGet) or a list of advisory IDs into one chronological timeline: publication, last modification, withdrawal and fix releases with their registry release dates (npm and PyPI). For each advisory it lists affected version ranges and fixed versions, and measures how long before or after disclosure the fix shipped and how long vulnerable versions were current. Paste OSV JSON to work offline.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://securityadvisorytimeline.usefulweb.site/ (interactive tool at https://securityadvisorytimeline.usefulweb.site/tool)
- JSON API: POST https://securityadvisorytimeline.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://securityadvisorytimeline.usefulweb.site/api/v1/tool)
- OpenAPI: https://securityadvisorytimeline.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://securityadvisorytimeline.usefulweb.site/mcp - tool `security_advisory_timeline`

## Inputs
- ecosystem (select): Ecosystem
- packageName (text): Package name
- advisoryIds (textarea): Or advisory IDs (one per line)
- osvJson (textarea): Or paste OSV JSON (offline) - Response of POST https://api.osv.dev/v1/query, an array of OSV records, or one record.
- releaseTimesJson (textarea): Optional: pasted release dates (offline) - npm packument (uses "time"), PyPI JSON (uses "releases") or {"1.2.3": "2024-01-01T00:00:00Z"}.
- fetchReleaseDates (boolean): Look up fix release dates (npm / PyPI registry)

## Method
- Package mode: POST https://api.osv.dev/v1/query with {package:{name, ecosystem}} (up to 5 result pages). ID mode: GET https://api.osv.dev/v1/vulns/{id} for up to 50 IDs. Withdrawn advisories are kept and marked.
- Affected ranges are rebuilt from OSV range events (introduced / fixed / last_affected / limit); GIT commit ranges are skipped. "last_affected" means no fixed version is published in the record.
- Release dates: npm registry packument "time" field (registry.npmjs.org/<name>) or the PyPI JSON API (earliest upload_time_iso_8601 per release). Other ecosystems: paste a {version: date} map.
- Fix→disclosure days = advisory published − first fixed release date (positive: the fix shipped before the advisory, typical for coordinated disclosure; negative: users were exposed after disclosure). Vulnerable window = first fixed release − release of the introducing version (or the first release when "introduced: 0").