🛡️ Vulners Python SDK
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
Why Vulners?
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
Installation
pip install -U vulners
Requires 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.
From a branch checkout (unreleased)
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 checkout
Or install that branch directly, without cloning:
pip install "git+https://github.com/vulnersCom/[email protected]"
Quickstart
from vulners import Vulners
# Get a free API key at https://vulners.com (or export VULNERS_API_KEY).
with Vulners(api_key="YOUR_API_KEY_HERE") as v:
# 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")
if log4shell is not None and log4shell.cvss is not None:
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)
for bulletin in page.data:
print(bulletin.id, bulletin.title)
Tip: keep your key out of source code — read it from the environment:
import os from vulners import Vulners v = Vulners(api_key=os.environ["VULNERS_API_KEY"])
Async
The same API is available on AsyncVulners:
import asyncio
from vulners import AsyncVulners
async def main():
async with AsyncVulners(api_key="YOUR_API_KEY_HERE") as v:
page = await v.search.query("Fortinet AND RCE", limit=20)
for bulletin in page.data:
print(bulletin.id, bulletin.title)
asyncio.run(main())
Usage examples
Runnable scripts for every task live under
samples/ — a v4 set and a matching
v3 (legacy) set, side by side.
Find public exploits for a CVE
for exploit in v.search.query("bulletinFamily:exploit AND CVE-2023-20198", limit=10).data:
print(exploit.id, exploit.href)
Audit installed software for known CVEs
# Mix product/version dicts and raw CPE 2.3 strings.
for item in v.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")
Audit a Linux host by installed packages
report = v.audit.linux_audit(os_name="debian", os_version="10",
packages=["openssl 1.1.1d-0+deb10u3 amd64"])
for issue in report["issues"]:
print(issue["package"])
Look up a package's license
from vulners import Vulners
with Vulners(api_key="YOUR_API_KEY_HERE") as v:
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']
Stream the archive (lazily, without buffering gigabytes)
for record in v.archive.iter_collection("cve"):
... # each record is yielded as it arrives (a lazily-streamed JSON array)
Handle errors
from vulners import Vulners, APIError, RateLimitError
try:
with Vulners(api_key="YOUR_API_KEY_HERE") as v:
cve = v.search.get_bulletin("CVE-2021-44228")
except RateLimitError as err:
print("slow down; retry after", err.retry_after, "s")
except APIError as err:
print(err.status_code, err.error_code, err.message) # the server's problem description
Data models
Every 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.
from vulners import Vulners, CveBulletin
with Vulners() as v: # reads VULNERS_API_KEY
cve = v.search.get_bulletin("CVE-2021-44228")
if isinstance(cve, CveBulletin):
print(cve.cwe) # typed, cve-specific field — IDE-completed
The full hierarchy — every family and collection with its fields, descriptions and examples, generated from live data — is browsable in the Data models reference.
Proxies
Route traffic through a proxy with proxy=, or let the client pick up the standard proxy
environment variables:
from vulners import Vulners
# 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.
AI agents (MCP)
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 server
It 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.
Backward compatibility
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:
import vulners
api = vulners.VulnersApi(api_key="YOUR_API_KEY_HERE") # still works exactly as before
cve = api.search.get_bulletin("CVE-2021-44228") # returns a dict, as it always did
New code should prefer the Vulners / AsyncVulners clients above. Migrate at your own pace — see
the migration guide.
Getting an API key
- 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.
Documentation
Compatibility
- Python: 3.10, 3.11, 3.12, 3.13, 3.14
- Platforms: Linux, macOS, Windows
- Vulners API: v3 and v4 endpoints
Contributing
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 + tests
See CONTRIBUTING.md for the full workflow.
Security
Found a security issue in the SDK? Please report it privately — see SECURITY.md. Do not open a public issue for vulnerabilities.
License
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
