{ "openapi": "3.1.1", "info": { "title": "Security Advisory Timeline API", "version": "1.0.0", "summary": "Disclosures, affected ranges, fixes and withdrawals for a package on one timeline, with time-to-fix.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://securityadvisorytimeline.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Disclosures, affected ranges, fixes and withdrawals for a package on one timeline, with time-to-fix.", "description": "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.\n\nMethodology:\n- 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.\n- 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.\n- Release dates: npm registry packument \"time\" field (registry.npmjs.org/) or the PyPI JSON API (earliest upload_time_iso_8601 per release). Other ecosystems: paste a {version: date} map.\n- 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\").", "tags": [ "security" ], "x-mcp-tool": "security_advisory_timeline", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityAdvisoryTimelineInput" }, "examples": { "example1": { "summary": "Pasted OSV records (fictional package)", "value": { "ecosystem": "npm", "packageName": "demo-parser", "osvJson": "[{\"id\":\"EXAMPLE-0001\",\"summary\":\"Prototype pollution in demo-parser merge()\",\"published\":\"2024-03-12T10:00:00Z\",\"modified\":\"2024-04-01T08:00:00Z\",\"database_specific\":{\"severity\":\"HIGH\"},\"affected\":[{\"package\":{\"ecosystem\":\"npm\",\"name\":\"demo-parser\"},\"ranges\":[{\"type\":\"SEMVER\",\"events\":[{\"introduced\":\"0\"},{\"fixed\":\"1.4.2\"},{\"introduced\":\"2.0.0\"},{\"fixed\":\"2.1.1\"}]}]}]},{\"id\":\"EXAMPLE-0002\",\"summary\":\"ReDoS in demo-parser tokenizer\",\"published\":\"2024-09-02T09:00:00Z\",\"modified\":\"2024-09-03T09:00:00Z\",\"database_specific\":{\"severity\":\"MODERATE\"},\"affected\":[{\"package\":{\"ecosystem\":\"npm\",\"name\":\"demo-parser\"},\"ranges\":[{\"type\":\"SEMVER\",\"events\":[{\"introduced\":\"2.0.0\"},{\"last_affected\":\"2.3.0\"}]}]}]},{\"id\":\"EXAMPLE-0003\",\"summary\":\"Incorrectly reported path traversal\",\"published\":\"2023-11-20T12:00:00Z\",\"modified\":\"2023-12-01T12:00:00Z\",\"withdrawn\":\"2023-12-01T12:00:00Z\",\"database_specific\":{\"severity\":\"LOW\"},\"affected\":[{\"package\":{\"ecosystem\":\"npm\",\"name\":\"demo-parser\"},\"ranges\":[{\"type\":\"SEMVER\",\"events\":[{\"introduced\":\"1.0.0\"},{\"fixed\":\"1.3.0\"}]}]}]}]", "releaseTimesJson": "{\"1.0.0\":\"2022-01-10T00:00:00Z\",\"1.3.0\":\"2023-06-01T00:00:00Z\",\"1.4.0\":\"2023-10-01T00:00:00Z\",\"1.4.2\":\"2024-03-05T00:00:00Z\",\"2.0.0\":\"2023-12-15T00:00:00Z\",\"2.1.1\":\"2024-03-06T00:00:00Z\",\"2.3.0\":\"2024-08-20T00:00:00Z\"}", "fetchReleaseDates": false } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityAdvisoryTimelineResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "SecurityAdvisoryTimelineInput": { "type": "object", "additionalProperties": false, "properties": { "ecosystem": { "title": "Ecosystem", "type": "string", "enum": [ "npm", "PyPI", "Go", "crates.io", "Maven", "RubyGems", "Packagist", "NuGet" ], "default": "npm" }, "packageName": { "title": "Package name", "type": "string", "maxLength": 214 }, "advisoryIds": { "title": "Or advisory IDs (one per line)", "type": "string", "maxLength": 5000 }, "osvJson": { "title": "Or paste OSV JSON (offline)", "description": "Response of POST https://api.osv.dev/v1/query, an array of OSV records, or one record.", "type": "string", "maxLength": 3000000 }, "releaseTimesJson": { "title": "Optional: pasted release dates (offline)", "description": "npm packument (uses \"time\"), PyPI JSON (uses \"releases\") or {\"1.2.3\": \"2024-01-01T00:00:00Z\"}.", "type": "string", "maxLength": 5000000 }, "fetchReleaseDates": { "title": "Look up fix release dates (npm / PyPI registry)", "type": "boolean", "default": true } }, "required": [] }, "SecurityAdvisoryTimelineResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "target", "dataSource", "advisories", "metrics", "events" ], "properties": { "target": { "type": [ "string", "null" ] }, "dataSource": { "type": "string", "enum": [ "osv-package", "osv-ids", "pasted" ] }, "advisories": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "aliases", "summary", "severity", "cvss", "package", "published", "modified", "withdrawn", "affectedRanges", "fixedVersions", "firstFixRelease", "firstFixReleaseDate", "introducedReleaseDate", "daysFixToDisclosure", "vulnerableWindowDays", "url" ], "properties": { "id": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "severity": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MODERATE", "LOW", "UNKNOWN" ] }, "cvss": { "type": [ "string", "null" ] }, "package": { "type": [ "string", "null" ] }, "published": { "type": [ "string", "null" ] }, "modified": { "type": [ "string", "null" ] }, "withdrawn": { "type": [ "string", "null" ] }, "affectedRanges": { "type": "array", "items": { "type": "string" } }, "fixedVersions": { "type": "array", "items": { "type": "string" } }, "firstFixRelease": { "type": [ "string", "null" ] }, "firstFixReleaseDate": { "type": [ "string", "null" ] }, "introducedReleaseDate": { "type": [ "string", "null" ] }, "daysFixToDisclosure": { "type": [ "integer", "null" ] }, "vulnerableWindowDays": { "type": [ "integer", "null" ] }, "url": { "type": "string" } } } }, "metrics": { "type": "object", "additionalProperties": false, "required": [ "advisories", "active", "withdrawn", "withoutFix", "withFixDate", "fixBeforeDisclosure", "medianDaysFixToDisclosure", "medianVulnerableWindowDays", "firstPublished", "lastPublished" ], "properties": { "advisories": { "type": "integer" }, "active": { "type": "integer" }, "withdrawn": { "type": "integer" }, "withoutFix": { "type": "integer" }, "withFixDate": { "type": "integer" }, "fixBeforeDisclosure": { "type": "integer" }, "medianDaysFixToDisclosure": { "type": [ "integer", "null" ] }, "medianVulnerableWindowDays": { "type": [ "integer", "null" ] }, "firstPublished": { "type": [ "string", "null" ] }, "lastPublished": { "type": [ "string", "null" ] } } }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "time", "kind", "advisory", "detail" ], "properties": { "time": { "type": "string" }, "kind": { "type": "string", "enum": [ "published", "modified", "withdrawn", "fix-released", "introduced" ] }, "advisory": { "type": "string" }, "detail": { "type": "string" } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }