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 Python.
Documentation · API Reference · 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 — ground AI agents and copilots on live vulnerability facts, with fully typed responses
Powering vulnerability scanners, CI/CD security gates, remediation-prioritization and threat-intelligence pipelines, SBOM analyzers, MSSP platforms and AI security agents — with production-grade rate limiting and typed responses out of the box.
pip install -U vulnersRequires Python 3.10+. The only runtime dependencies are
httpx, pydantic, and
orjson.
import vulners
# Get a free API key at https://vulners.com
api = vulners.VulnersApi(api_key="YOUR_API_KEY_HERE")
# Look up a CVE
log4shell = api.search.get_bulletin("CVE-2021-44228")
print(log4shell["id"], "—", log4shell["title"])
# Search the database with Lucene syntax
critical = api.search.search_bulletins("type:cve AND cvss.score:[9 TO 10]", limit=10)
for bulletin in critical:
print(bulletin["id"], bulletin["title"])Tip: keep your key out of source code — read it from the environment instead:
import os api = vulners.VulnersApi(api_key=os.environ["VULNERS_API_KEY"])
Every snippet below is a runnable, real script under samples/.
for doc in api.search.search_bulletins("Fortinet AND RCE order:published", limit=5):
print(doc["id"], "-", doc["title"])for exploit in api.search.search_exploits("CVE-2023-20198", limit=10):
print(exploit["id"], exploit["href"])# Mix product/version dicts and raw CPE 2.3 strings.
for item in api.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")
# cpe:2.3:a:apache:log4j:2.14.1:... -> 12 vulnerabilities# dpkg-query -W -f='${Package} ${Version} ${Architecture}\n' (or rpm -qa ...)
report = api.audit.linux_audit(os_name="debian", os_version="10",
packages=["openssl 1.1.1d-0+deb10u3 amd64"])
for issue in report["result"]["issues"]:
print(issue["package"])try:
with vulners.VulnersApi(api_key="YOUR_API_KEY_HERE") as api: # releases the pool on exit
cve = api.search.get_bulletin("CVE-2021-44228")
print(cve["cvss"]["score"], cve["cvss"]["severity"]) # 10.0 CRITICAL
except vulners.VulnersApiError as err:
print(err.http_status, err.error_code, err.message) # the server's problem descriptionMore recipes — software/Linux/SBOM audits, CPE search, exploits — live in
samples/ and the official API reference.
- Create a free account at vulners.com.
- Follow the authentication guide to generate a key.
- Pass it to
VulnersApi(api_key=...), or exportVULNERS_API_KEYand read it from the environment.
Never commit your API key. The SDK sends it only in the X-Api-Key header, strips it on
cross-origin redirects, and keeps it out of exception messages and object reprs.
This release keeps the observable behavior of successful calls 100% backward compatible while repairing broken paths and hardening the client:
- 🐍 PEP 561 typed — ships
py.typed, so editors and type checkers see the full API. - 🔁 Reliable rate limiting — the token bucket no longer stalls on low or malformed server limits and is now thread-safe and per-instance.
- 🧯 Honest error handling — HTTP errors and malformed bodies raise
VulnersApiErrorinstead of being silently returned as data. - 🔐 Security hardening — the API key is masked in reprs and errors, stripped on
cross-origin and internal-address redirects, and an opt-in
max_response_bytesguard bounds decompression of untrusted archives. - 🧹 Context-manager support, accurate deprecation warnings, and
vulners.__version__.
See the CHANGELOG for the full list.
| Resource | Link |
|---|---|
| 📖 Full documentation | https://docs.vulners.com/docs/ |
| 🔌 API reference | https://docs.vulners.com/docs/api/ |
| 🧪 Interactive API (Swagger) | https://docs.vulners.com/docs/api/swagger/ |
| 🔑 Authentication / API keys | https://docs.vulners.com/docs/quickstart/authentication/ |
| 🧬 Data model | https://docs.vulners.com/docs/ |
| 💡 Examples | samples/ |
- 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. Run the test suite with:
poetry install
poetry run pytestFound a security issue in the SDK? Please report it responsibly — see SECURITY.md if present, or contact the Vulners team via vulners.com. Do not open a public issue for vulnerabilities.
Distributed under the GNU GPL v3.0. 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