The official Python client for the Vulners intelligence graph lets authorized security teams search CVEs, map exploits to assets, and audit hosts and SBOMs from typed, async-ready code.
| Tool | vulnersCom/api — official Python SDK for the Vulners vulnerability-intelligence API |
| Category | Python SDK / threat-intelligence API client with MCP server |
| Primary Use | Searching and enriching CVEs with CVSS, EPSS and exploitation status, and auditing software, Linux hosts and SBOMs against the Vulners graph |
| Safe Use | Defensive vulnerability management, authorized internal asset assessment, and research pipelines on systems you own or are contracted to assess |
| Telemetry Note | Purely defensive telemetry consumer: all queries hit vulners.com with an X-Api-Key header; API-side request logs are the observability surface, nothing touches target hosts |
vulnersCom/api is the official Python SDK for the Vulners platform, which the README describes as a vulnerability-intelligence graph aggregating more than 230 sources — CVEs, exploits, vendor advisories, CISA KEV, EPSS and AI risk scores — into a single queryable API. The package, published on PyPI as vulners under an MIT license, is not a scanner you point at machines; it is an API-first client for pulling risk-prioritized intelligence about software you already know you run. That framing matters for authorized workflows: nothing in the SDK needs agents, network access to targets, or privileged credentials on assessed systems. You send identifiers — CPE strings, package lists, SBOM artifacts — and get back structured vulnerability data. The repository shows 377 stars, Python as the primary language, and a topic list that spans cve, epss, sbom, threat-intelligence and mcp, which accurately previews the breadth of the client.
Installation is deliberately frictionless: pip install -U vulners pulls the entire modern transport stack — httpx for HTTP, pydantic for typed models, orjson for fast JSON — plus h2 for HTTP/2, brotli and zstandard compression, isal for ISA-L-accelerated gzip, and ijson/stream-unzip for lazily decoding the archive streams. Everything ships as prebuilt wheels, so there is no build step even on locked-down corporate images. The README notes Python 3.10+ is required, and that the unreleased v4.0 lives on a branch, installable with pip install "git+https://github.com/vulnersCom/api.git@v4.0" — a signal that the maintainers treat the GitHub default branch as the cutting edge while PyPI carries the stable line.
The core interface is the Vulners client, used as a context manager, with an AsyncVulners twin exposing the identical surface over asyncio. Authentication is a free API key from vulners.com, passed as Vulners(api_key=...) or read from the VULNERS_API_KEY environment variable. The README is explicit about key hygiene: never commit keys, and prefer environment injection. On the wire the key travels in an X-Api-Key header, with a few legacy endpoints receiving it in the body (webhooks, subscription mutations, win_audit) or query string (webhooks.read()). Notably, the client strips the key on cross-origin redirects, refuses redirects to internal addresses — a nice SSRF-conscious touch for server-side integrations — and keeps the key out of exception messages and reprs.
The search resource is the primary intelligence surface. v.search.get_bulletin("CVE-2021-44228") returns a typed model or None, exposing fields like cvss.score and cvss.vector directly. Free-text and structured queries use Lucene syntax, e.g. v.search.query("type:cve AND cvss.score:[9 TO 10]", limit=10), and a subtle design decision is worth flagging: pages auto-paginate when iterated, so the limit parameter is page size, not a hard result cap. This is the kind of ergonomic detail that tells you the authors expect operators to enumerate large result windows in enrichment pipelines rather than run one-off lookups.
Where the SDK earns its keep in a defensive program is the audit resource. v.audit.software() accepts a mixed list of product/version dicts and raw CPE 2.3 strings and returns matched vulnerabilities per item — effectively a batch matcher between your inventory and the intelligence graph. v.audit.linux_audit() takes an OS name, version and installed-package strings (the README's example uses a Debian 10 package line) and returns a structured issues report. There is also v.audit.metadata() for license lookups across registries like pypi and maven, with careful semantics: found=True with an empty license list means known-but-unrecorded, while found=False means the registry does not know the package at all. Maven coordinates are lower-cased automatically so you never fight groupId:artifactId casing conventions.
The data-modeling layer is the most architecturally interesting part of the README. Every document is a bulletin, modeled in three typed tiers: a base Bulletin with universal fields (id, title, cvss, published), family models like CveBulletin and ExploitBulletin keyed on bulletinFamily, and per-collection models keyed on source type. The SDK returns the most specific model that fits and every model sets extra="allow", so fields the API adds before the SDK catches up are still present on the object rather than silently dropped. For a professional consumer of third-party intelligence, that forward-compatibility guarantee is a big deal — it means an upstream schema addition will not break your enrichment job at 3 a.m.
The archive resource addresses the mirror-and-pipeline use case: v.archive.iter_collection("cve") yields records as they arrive from a lazily-streamed JSON array, without buffering gigabytes in memory, and the platform offers hourly updates for keeping a local mirror current. Complementing that, the alerts subsystem lets you subscribe a webhook to a saved query, so new vulnerabilities matching your stack arrive as push notifications rather than polling. Combined, these two features turn the SDK from a lookup tool into a substrate for continuous vulnerability-intelligence pipelines — the pattern mature security teams use to drive SLA timers on patching.
For AI-assisted workflows, the package ships an optional MCP server: pip install "vulners[mcp]" then vulners-mcp runs a self-hosted Model Context Protocol endpoint exposing typed tools for search, CVE lookup, exploit lookup and audits to any MCP-compatible client. The README distinguishes this minimal bundled server from the fully managed hosted endpoint at https://mcp.vulners.com/. From a grounding perspective this is the right architecture — agents get live, structured vulnerability facts instead of hallucinated scores, and AGENTS.md documents the toolset for agent integrators.
Error handling is first-class rather than an afterthought. The SDK raises RateLimitError carrying a machine-readable retry_after and APIError with status_code, error_code and server-provided message, which makes backoff logic trivial to implement. Proxy support covers corporate egress requirements: an explicit proxy= argument (including authenticated httpx.Proxy objects) or standard HTTPS_PROXY/HTTP_PROXY/ALL_PROXY environment variables honored when trust_env=True (the default), with NO_PROXY respected. These are exactly the constraints that determine whether a tool survives deployment in a real enterprise.
Migration is handled with unusual care: the entire 3.x surface — VulnersApi, VScannerApi, every method and import path — is preserved unchanged in 4.0, so existing integrations keep working with dict-returning semantics while new code adopts Vulners/AsyncVulners and typed models at its own pace. The samples/ directory ships runnable scripts for every task in both v4 and legacy v3 variants side by side, which is a pragmatic documentation strategy. For defenders and authorized assessors building enrichment, triage or SBOM-matching automation on solid, typed foundations, this SDK is one of the more thoughtfully engineered clients in the vulnerability-intelligence space, and the documentation depth — generated model references, migration guides, Swagger — reflects a project that expects long-lived production use.
vulnersCom/api.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.