VulnersCom Api

🛡️ 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.

[](https://pypi.org/project/vulners/) [](https://pypi.org/project/vulners/) [](https://pypi.org/project/vulners/) [](https://github.com/vulnersCom/api/actions/workflows/ci.yml) [](LICENSE) [](https://peps.python.org/pep-0561/)

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](#ai-agents-mcp), 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/api.git@v4.0"

---

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: > ``python > 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/](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"])

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 per

bulletinFamily, 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](AGENTS.md).

> Hosted vs. bundled. For a fully managed, always-on endpoint, use the official hosted > server at ** — no install required. The vulners-mcp shipped > 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

1. Create a free account at vulners.com.
2. Follow the authentication guide

to generate a key.

1. Pass it to Vulners(api_key=...), or export VULNERS_API_KEY and 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

| 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/](samples/) | | 🤝 Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) | | 🔒 Security policy | [SECURITY.md](SECURITY.md) |

---

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](CONTRIBUTING.md) for the full workflow.

---

Security

Found a security issue in the SDK? Please report it privately — see [SECURITY.md](SECURITY.md). Do not open a public issue for vulnerabilities.

---

License

Distributed under the MIT License. See [LICENSE](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vulnersCom
• Source: vulnersCom/api
• License: MIT
• Homepage: https://vulners.com

Install and usage instructions live in the source repository linked above.