OSV integration
Use vuln.mlab.sh as a package-scoped, OSV-compatible vulnerability gate.
POST /api/v2/query is a package-scoped lookup designed to let vuln.mlab.sh act
as an OSV source - for example a
batlehub VulnerabilityScanner.
Unlike keyword search (/api/v1/cve), it returns only the vulnerabilities
affecting the exact coordinate you query - never a free-text match - which is the
hard requirement for a blocking CVE gate. Request and response shapes are OSV's
/v1/query, verbatim.
Query by PURL
curl -s -X POST "https://vuln.mlab.sh/api/v2/query" \
-H 'Content-Type: application/json' \
-d '{"package":{"purl":"pkg:cargo/[email protected]"}}'Query by ecosystem + name
curl -s -X POST "https://vuln.mlab.sh/api/v2/query" \
-H 'Content-Type: application/json' \
-d '{"package":{"ecosystem":"crates.io","name":"time"},"version":"0.1.44"}'vulns is always present, normalized to [] when the coordinate has no known
vulnerabilities.
Status semantics
This endpoint uses real HTTP status codes - unlike the v1 API, which always
returns 200. This lets a blocking gate tell "clean" apart from "outage":
| Status | Meaning |
|---|---|
200 | Query succeeded. Body is { "vulns": [...] }, possibly empty. |
400 | Malformed JSON, or not a package-scoped query. |
502 | Upstream OSV transport error. Outage - not "no vulns". |
503 | Upstream OSV rate limit (Retry-After: 30). Outage - not "no vulns". |
A client must not treat an outage (502/503) as an empty finding set, or a
transient blip would silently clear previously-recorded vulnerabilities.
Wiring into batlehub
Point the [vulnerability_scan] OSV source's base URL at https://vuln.mlab.sh
and have the adapter use the /api/v2/query path (the reference OsvScanner
hardcodes /v1/query, so the path is the only change). The OSV request body,
response parsing and fixed_version extraction all work unchanged.