api AGENTS.md

AGENTS.md — using the Vulners Python SDK

Guidance for AI agents (and their humans) using this SDK to work with the Vulners vulnerability intelligence API. For contributor/development conventions, see .agents/skills/vulners-api/SKILL.md instead.

Install & authenticate

pip install vulners            # core
pip install "vulners[mcp]"     # + the MCP server (see below)

Working inside a repository checkout? Use uv sync --locked and uv run python .... Do not run pip install vulners — that installs the currently published release rather than this checkout. (For development conventions and commands, see .agents/skills/vulners-api/SKILL.md.)

The API key comes from the VULNERS_API_KEY environment variable, or is passed explicitly. Get a free key at https://vulners.com. Never hard-code a key in committed code.

Two ways to use it

1. As a library

Prefer the v4 clients: Vulners (sync) and AsyncVulners (async). Both are context managers and expose the same resource namespaces.

from vulners import Vulners

with Vulners() as v:                      # reads VULNERS_API_KEY
    # Search (Lucene syntax → typed Bulletin models; access fields as attributes)
    for b in v.search.query("type:cve AND cvss.score:[9 TO 10]", limit=10):
        print(b.id, b.title, b.cvss and b.cvss.score)

    # Single lookup (-> Bulletin | None)
    cve = v.search.get_bulletin("CVE-2021-44228")

    # Audit software / Linux host
    v.audit.software(["cpe:2.3:a:apache:log4j:2.14.1"])
    v.audit.linux_audit(os_name="debian", os_version="10",
                        packages=["openssl 1.1.1d-0+deb10u3 amd64"])

Key entry points:

Namespace	What it does	Common methods
v.search	search & fetch documents	query, iter_query, get_bulletin, get_multiple_bulletins
v.documents	document-centric lookups	get, get_many, references, history
v.audit	vulnerability assessment	software, host, linux_audit, library_audit, sbom_audit, cve_audit, kb_audit, win_audit, smart
v.archive	bulk dataset download	fetch_collection, iter_collection (stream), fetch_collection_update
v.misc	lookups	search_cpe, query_autocomplete, get_suggestion
v.subscriptions	current v4 subscriptions API	list, get, create, update, delete
v.subscriptions_email	legacy v3 email subscriptions	list, add, edit, delete
v.webhooks	legacy v3 polling webhook subscriptions	list, add, read, delete
v.report · v.stix · v.vscanner	reporting, STIX bundles, VScanner	—