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

PyPI version Python versions Downloads CI License: MIT Typed

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/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:

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"])

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.

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-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.
  3. 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/
🤝 Contributing CONTRIBUTING.md
🔒 Security policy 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 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

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.3.0)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for vulners from gravatar.com vulners Avatar for zeloff from gravatar.com zeloff

Credits

Author/Maintainer: Vulners

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

mcp otel

Tags

security vulnerability vulners CVE CVSS EPSS exploit threat-intelligence vulnerability-management sbom audit

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vulners-4.1.0.tar.gz (174.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vulners-4.1.0-py3-none-any.whl (226.7 kB view details)

Uploaded Python 3

File details

Details for the file vulners-4.1.0.tar.gz.

File metadata

  • Download URL: vulners-4.1.0.tar.gz
  • Upload date:
  • Size: 174.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vulners-4.1.0.tar.gz
Algorithm Hash digest
SHA256 6c10821243deeec2eb2b0aa828c21e073418fbefd3368a710771639cb728ad5b
MD5 e39348b1ae9e52f8f6101ed5c1941a15
BLAKE2b-256 b6a1d0c7986cac03bfcd7520c24d5679a05ae44ad77ce5ddd1d1dd0f0968834e

See more details on using hashes here.

Provenance

The following attestation bundles were made for vulners-4.1.0.tar.gz:

Publisher: release.yml on vulnersCom/api

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vulners-4.1.0-py3-none-any.whl.

File metadata

  • Download URL: vulners-4.1.0-py3-none-any.whl
  • Upload date:
  • Size: 226.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vulners-4.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0993d83c01765c282232d61fe24a84daab98f667b1fb633bf6e9272dfea65729
MD5 cac18fc32ac2101235145b8b46b7af62
BLAKE2b-256 518dddcfc6286a6ef3963c826d9f04191c98871273d7fb9b52a29c839e27bb0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for vulners-4.1.0-py3-none-any.whl:

Publisher: release.yml on vulnersCom/api

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.3.0

2 files

4.2.0

2 files

This release

4.1.0 This release

2 files

4.0.1

2 files

4.0.0

2 files

3.2.0

2 files

3.1.11

2 files

3.1.10

2 files

3.1.9

2 files

3.1.8

2 files

3.1.7

2 files

3.1.6

2 files

3.1.5

2 files

3.1.3

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.6

2 files

3.0.5

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

2.3.7

2 files

2.3.6

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.7

2 files

2.1.5

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.10

3 files

2.0.9

3 files

2.0.8

3 files

2.0.6

3 files

2.0.5

3 files

2.0.4

3 files

2.0.3

3 files

2.0.2

3 files

2.0.1

3 files

2.0.0

3 files

1.5.18

3 files

1.5.17

3 files

1.5.16

3 files

1.5.15

3 files

1.5.14

3 files

1.5.13

3 files

1.5.12

3 files

1.5.11

3 files

1.5.10

3 files

1.5.9

3 files

1.5.8

3 files

1.5.7

3 files

1.5.5

3 files

1.5.4

3 files

1.5.3

3 files

1.5.2

3 files

1.5.1

3 files

1.5.0

3 files

1.4.9

3 files

1.4.7

3 files

1.4.6

3 files

1.4.5

3 files

1.4.4

3 files

1.4.3

3 files

1.4.2

3 files

1.4.1

3 files

1.4.0

3 files

1.3.6

3 files

1.3.5

3 files

1.3.4

3 files

1.3.3

3 files

1.3.2

3 files

1.3.1

3 files

1.3.0

3 files

1.2.1

3 files

1.2.0

3 files

1.1.3

3 files

1.1.1

3 files

1.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page