# VulnersCom Api

> Official Python SDK for the Vulners vulnerability-intelligence API — search CVEs, exploits and advisories (CVSS/EPSS/KEV), audit software, Linux/Windows hosts and SBOMs, and stream the whole graph. Typed sync + async clients, 100% v3-compatible, with a built-in MCP server for AI agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-vulnerscom-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vulnersCom](https://agentstack.voostack.com/s/vulnerscom)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vulnersCom](https://github.com/vulnersCom)
- **Source:** https://github.com/vulnersCom/api
- **Website:** https://vulners.com

## Install

```sh
agentstack add mcp-vulnerscom-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🛡️ Vulners Python SDK

### The official Python client for [Vulners](https://vulners.com) — 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**](https://vulnersCom.github.io/api/) ·
[**Data models**](https://vulnersCom.github.io/api/reference/bulletins/) ·
[**Get an API key**](https://docs.vulners.com/docs/quickstart/authentication/) ·
[**Vulners.com**](https://vulners.com)

---

## Why Vulners?

[Vulners](https://vulners.com) 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

```bash
pip install -U vulners
```

Requires **Python 3.10+**. A plain `pip install vulners` pulls everything needed for fast, modern
transport — [`httpx`](https://www.python-httpx.org/), [`pydantic`](https://docs.pydantic.dev/) and
[`orjson`](https://github.com/ijl/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:

```bash
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:

```bash
pip install "git+https://github.com/vulnersCom/api.git@v4.0"
```

---

## Quickstart

```python
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`:

```python
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

```python
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

```python
# 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

```python
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)

```python
for record in v.archive.iter_collection("cve"):
    ...  # each record is yielded as it arrives (a lazily-streamed JSON array)
```

### Handle errors

```python
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.

```python
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](https://vulnersCom.github.io/api/reference/bulletins/)**.

---

## Proxies

Route traffic through a proxy with `proxy=`, or let the client pick up the standard proxy
environment variables:

```python
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](https://vulnersCom.github.io/api/how-to/proxy-timeout-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](https://modelcontextprotocol.io) server:

```bash
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:

```python
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](https://vulnersCom.github.io/api/explanation/migration/).

---

## Getting an API key

1. Create a free account at **[vulners.com](https://vulners.com)**.
2. Follow the [authentication guide](https://docs.vulners.com/docs/quickstart/authentication/#how-to-obtain-api-key)
   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/`](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](https://docs.astral.sh/uv/):

```bash
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](https://vulners.com) 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](https://github.com/vulnersCom)
- **Source:** [vulnersCom/api](https://github.com/vulnersCom/api)
- **License:** MIT
- **Homepage:** https://vulners.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vulnerscom-api
- Seller: https://agentstack.voostack.com/s/vulnerscom
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.