The official Python client for Vulners — the vulnerability intelligence graph to build on
Query CVEs, exploits and advisories enriched with CVSS, EPSS and exploitation status; assess your software, hosts and SBOMs for the vulnerabilities that affect them; and stream the whole graph for your own pipelines — all from a few lines of typed, async-ready Python.
SDK documentation · Data models · Get an API key · Vulners.com
Vulners aggregates 230+ sources — CVEs, exploits, vendor advisories, CISA KEV, EPSS and AI risk scores — into one queryable vulnerability-intelligence graph, so you can prioritize what to fix beyond raw CVSS. It is API-first and needs no agents or network access: send asset data in standard formats, get back risk-prioritized intelligence.
This SDK is the fastest way to build on that graph from Python:
- 🔎 Intelligence — search and enrich CVEs, bulletins and advisories with CVSS, EPSS, KEV and exploitation context
- 🧨 Exploits — track active exploitation and pull proof-of-concept code for a product or CVE
- 🖥️ Assessment — find the vulnerabilities affecting your software, Linux/Windows hosts, KBs, libraries and SBOMs
- 🗄️ Datasets — stream the full graph (and hourly updates) into your own pipelines and mirrors
- 🔔 Alerts — subscribe to new vulnerabilities matching a query and get notified via webhook
- 🤖 AI-ready — a built-in MCP server, typed bulletin models and documented response shapes to ground AI agents on live vulnerability facts
pip install -U vulnersRequires Python 3.10+. A plain pip install vulners pulls everything needed for fast, modern
transport — httpx, pydantic and
orjson, plus HTTP/2 (h2), response compression
(brotli/zstandard), ISA-L-accelerated gzip (isal) and streaming archive decode
(ijson/stream-unzip) — all with prebuilt wheels, so there is no build step.
The latest pre-release lives on the v4.0 branch (not yet on PyPI). Check the branch out
and install it from source:
git clone -b v4.0 https://github.com/vulnersCom/api.git
cd api
pip install -e .# editable install from the checkoutOr install that branch directly, without cloning:
pip install "git+https://github.com/vulnersCom/api.git@v4.0"fromvulnersimportVulners# Get a free API key at https://vulners.com (or export VULNERS_API_KEY).withVulners(api_key="YOUR_API_KEY_HERE") asv:
# Look up a CVE — you get back a typed model (or None if it isn't found).log4shell=v.search.get_bulletin("CVE-2021-44228")
iflog4shellisnotNoneandlog4shell.cvssisnotNone:
print(log4shell.id, "—", log4shell.title)
print(log4shell.cvss.score, log4shell.cvss.vector)
# Search with Lucene syntax. `limit` is the page size; read the first page here# (iterating the page itself auto-paginates the whole result window).page=v.search.query("type:cve AND cvss.score:[9 TO 10]", limit=10)
forbulletininpage.data:
print(bulletin.id, bulletin.title)Tip: keep your key out of source code — read it from the environment:
importosfromvulnersimportVulnersv=Vulners(api_key=os.environ["VULNERS_API_KEY"])
The same API is available on AsyncVulners:
importasynciofromvulnersimportAsyncVulnersasyncdefmain():
asyncwithAsyncVulners(api_key="YOUR_API_KEY_HERE") asv:
page=awaitv.search.query("Fortinet AND RCE", limit=20)
forbulletininpage.data:
print(bulletin.id, bulletin.title)
asyncio.run(main())Runnable scripts for every task live under
samples/ — a v4 set and a matching
v3 (legacy) set, side by side.
forexploitinv.search.query("bulletinFamily:exploit AND CVE-2023-20198", limit=10).data:
print(exploit.id, exploit.href)# Mix product/version dicts and raw CPE 2.3 strings.foriteminv.audit.software([{"product": "openssl", "version": "1.0.1"},
"cpe:2.3:a:apache:log4j:2.14.1"]):
print(item["matched_criteria"], "->", len(item["vulnerabilities"]), "vulnerabilities")report=v.audit.linux_audit(os_name="debian", os_version="10",
packages=["openssl 1.1.1d-0+deb10u3 amd64"])
forissueinreport["issues"]:
print(issue["package"])fromvulnersimportVulnerswithVulners(api_key="YOUR_API_KEY_HERE") asv:
meta=v.audit.metadata("pypi", "requests", "2.28.0")
print(meta.license) # ['ISC'] — always a list, never a bare string# An empty license with meta.found is True means "known, but no recorded license".# meta.found is False when the registry does not know the package name at all.unknown=v.audit.metadata("pypi", "no-such-package", "9.9.9")
print(unknown.found) # False# For Maven the name is the "groupId:artifactId" coordinate; the registry name is# lower-cased for you, so you never touch the colon-vs-slash / casing details.guava=v.audit.metadata("maven", "com.google.guava:guava", "30.0-jre")
print(guava.license) # ['Apache-2.0']forrecordinv.archive.iter_collection("cve"):
... # each record is yielded as it arrives (a lazily-streamed JSON array)fromvulnersimportVulners, APIError, RateLimitErrortry:
withVulners(api_key="YOUR_API_KEY_HERE") asv:
cve=v.search.get_bulletin("CVE-2021-44228")
exceptRateLimitErroraserr:
print("slow down; retry after", err.retry_after, "s")
exceptAPIErroraserr:
print(err.status_code, err.error_code, err.message) # the server's problem descriptionEvery document the API returns is a bulletin, and the SDK models them in three typed layers, so your editor and type checker know the exact shape at whatever level of detail you need:
Bulletin— the base fields every document carries (id,title,cvss,published, …).- Family models (
CveBulletin,ExploitBulletin,ScannerBulletin, …) — one perbulletinFamily, adding that family's shared fields. - Collection models — one per collection
type, adding the fields specific to that source.
search/archive/audit return the most specific model that fits a document (type →
bulletinFamily → Bulletin). Every field is optional (a missing one is None) and every model
keeps extra="allow", so a field the API adds before the SDK models it is still on the object —
nothing is ever dropped.
fromvulnersimportVulners, CveBulletinwithVulners() asv: # reads VULNERS_API_KEYcve=v.search.get_bulletin("CVE-2021-44228")
ifisinstance(cve, CveBulletin):
print(cve.cwe) # typed, cve-specific field — IDE-completedThe full hierarchy — every family and collection with its fields, descriptions and examples, generated from live data — is browsable in the Data models reference.
Route traffic through a proxy with proxy=, or let the client pick up the standard proxy
environment variables:
fromvulnersimportVulners# explicit (a URL, or httpx.Proxy(..., auth=(user, pass)) for an authenticated proxy)v=Vulners(api_key="YOUR_API_KEY_HERE", proxy="http://proxy.corp.example:8080")
# or from the environment — HTTPS_PROXY / HTTP_PROXY / ALL_PROXY, honoring NO_PROXY:# export HTTPS_PROXY="http://proxy.corp.example:8080"v=Vulners(api_key="YOUR_API_KEY_HERE")Environment proxies are used when you don't pass proxy= and leave trust_env=True (the
default). See
Proxies, timeouts & retries
for authenticated proxies and combining a proxy with custom TLS.
Ship live Vulners intelligence to AI agents and copilots via the built-in Model Context Protocol server:
pip install "vulners[mcp]"
VULNERS_API_KEY=... vulners-mcp # run the MCP serverIt exposes concise, typed tools — search bulletins, look up a CVE, find exploits, and audit
software/Linux/hosts — that any MCP-compatible client (Claude, IDE agents, …) can call. See
AGENTS.md.
Hosted vs. bundled. For a fully managed, always-on endpoint, use the official hosted server at https://mcp.vulners.com/ — no install required. The
vulners-mcpshipped in this package is a minimal, self-hosted implementation (a core set of tools) for embedding in your own environment.
Upgrading from 3.x is a drop-in. The entire v3 API — VulnersApi, VScannerApi, every method,
and all import paths — is preserved unchanged in 4.0:
importvulnersapi=vulners.VulnersApi(api_key="YOUR_API_KEY_HERE") # still works exactly as beforecve=api.search.get_bulletin("CVE-2021-44228") # returns a dict, as it always didNew code should prefer the Vulners / AsyncVulners clients above. Migrate at your own pace — see
the migration guide.
- Create a free account at vulners.com.
- Follow the authentication guide to generate a key.
- Pass it to
Vulners(api_key=...), or exportVULNERS_API_KEYand let the client read it.
Never commit your API key. The SDK authenticates with the X-Api-Key header; a few legacy
endpoints additionally send the key where the server requires it — in the request body (the
subscription and webhook mutations and win_audit) or the query string (webhooks.read()). On
every request it strips the key on cross-origin redirects, refuses redirects to internal
addresses, and keeps it out of exception messages and object reprs.
| Resource | Link |
|---|---|
| 📘 SDK documentation | https://vulnersCom.github.io/api/ |
| 🧬 Data models (bulletin hierarchy) | https://vulnersCom.github.io/api/reference/bulletins/ |
| 🔌 SDK API reference (clients, resources, exceptions) | https://vulnersCom.github.io/api/reference/clients/ |
| 🧭 Migration (v3 → v4) | https://vulnersCom.github.io/api/explanation/migration/ |
| 📖 Vulners platform docs | https://docs.vulners.com/docs/ |
| 🧪 Interactive API (Swagger) | https://docs.vulners.com/docs/api/swagger/ |
| 🔑 Authentication / API keys | https://docs.vulners.com/docs/quickstart/authentication/ |
| 💡 Examples | samples/ |
| 🤝 Contributing | CONTRIBUTING.md |
| 🔒 Security policy | SECURITY.md |
- Python: 3.10, 3.11, 3.12, 3.13, 3.14
- Platforms: Linux, macOS, Windows
- Vulners API: v3 and v4 endpoints
Issues and pull requests are welcome! Please open an issue to discuss substantial changes first. The project uses uv:
uv sync
make check # lint + typecheck + unasync-check + testsSee CONTRIBUTING.md for the full workflow.
Found a security issue in the SDK? Please report it privately — see SECURITY.md. Do not open a public issue for vulnerabilities.
Distributed under the MIT License. See LICENSE.
Built by the Vulners team. If this SDK helps secure your stack, please ⭐ the repo — it helps others find it.
Keywords: vulnerability intelligence · CVE · exploit intelligence · CVSS · EPSS · CISA KEV · risk prioritization · security advisories · SBOM · vulnerability assessment · vulnerability scanner · threat intelligence · vulnerability database · AI security agents · MCP · MSSP · DevSecOps · Python security · infosec