Skip to main content

VulnCheck Logo

The VulnCheck SDK For Python

Bring the VulnCheck API to your Python applications.

PyPI - Version Jupyter

Installation

# From PyPi
pip install vulncheck-sdk

[!IMPORTANT] Windows users may need to enable Long Path Support

Resources

Quickstart

import urllib.request
import vulncheck_sdk
import os

# First let's setup a few variables to help us
TOKEN = os.environ["VULNCHECK_API_TOKEN"]  # Remember to store your token securely!

# Now let's create a configuration object
configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

# Pass that config object to our API client and now...
with vulncheck_sdk.ApiClient(configuration) as api_client:
    # We can use two classes to explore the VulnCheck API: EndpointsApi & IndicesApi

    ### EndpointsApi has methods to query every endpoint except `/v3/index`
    # See the full list of endpoints here: https://docs.vulncheck.com/api
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    # PURL
    api_response = endpoints_client.purl_get("pkg:hex/coherence@0.1.2")
    data = V3controllersPurlResponseData = api_response.data
    print(data.cves)

    # CPE
    cpe = "cpe:/a:microsoft:internet_explorer:8.0.6001:beta"
    api_response = endpoints_client.cpe_get(cpe)
    for cve in api_response.data:
        print(cve)

    # Download a Backup
    index = "initial-access"
    api_response = endpoints_client.backup_index_get(index)
    file_path = f"{index}.zip"
    with urllib.request.urlopen(api_response.data[0].url) as response:
        with open(file_path, "wb") as file:
            file.write(response.read())

    ### IndicesApi has methods for each index
    indices_client = vulncheck_sdk.IndicesApi(api_client)

    # Add query parameters to filter what you need
    api_response = indices_client.index_vulncheck_nvd2_get(cve="CVE-2019-19781")

    print(api_response.data)
Click to View Async Implementation
import asyncio
import os
import aiohttp
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def run_vulnerability_checks():
    # Use 'async with' to manage the ApiClient connection pool
    async with vcaio.ApiClient(configuration) as api_client:
        endpoints_client = vcaio.EndpointsApi(api_client)
        indices_client = vcaio.IndicesApi(api_client)

        # --- PURL Search ---
        # 'await' the coroutine to get results
        purl_response = await endpoints_client.purl_get("pkg:hex/coherence@0.1.2")
        if purl_response.data:
            print(f"PURL CVEs: {purl_response.data.cves}")

        # --- CPE Search ---
        cpe = "cpe:/a:microsoft:internet_explorer:8.0.6001:beta"
        # 'await' the coroutine to get results
        cpe_response = await endpoints_client.cpe_get(cpe)
        print(f"CPE Results for {cpe}:")
        for cve in cpe_response.data:
            print(f" - {cve}")

        # --- Index Query (NVD2) ---
        # 'await' the coroutine to get results
        nvd_response = await indices_client.index_vulncheck_nvd2_get(
            cve="CVE-2019-19781"
        )
        print(f"NVD2 Data: {nvd_response.data}")

        # --- Download Backup (Async) ---
        index_name = "initial-access"
        # 'await' the coroutine to get results
        backup_response = await endpoints_client.backup_index_get(index_name)

        if backup_response.data:
            download_url = backup_response.data[0].url
            file_path = f"{index_name}.zip"

            print(f"Downloading backup from {download_url}...")
            # Use aiohttp (already in your environment) for async download
            async with aiohttp.ClientSession() as session:
                async with session.get(download_url) as resp:
                    if resp.status == 200:
                        # 'await' the coroutine to get results
                        content = await resp.read()
                        with open(file_path, "wb") as f:
                            f.write(content)
                        print(f"Saved backup to {file_path}")


if __name__ == "__main__":
    # Entry point to start the event loop
    asyncio.run(run_vulnerability_checks())

Examples

Advisory

List all advisory feeds and query advisories filtered by feed

import vulncheck_sdk
from vulncheck_sdk.models.search_v4_advisory_return_value import SearchV4AdvisoryReturnValue
from vulncheck_sdk.models.search_v4_list_feed_return_value import SearchV4ListFeedReturnValue
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    advisory_client = vulncheck_sdk.AdvisoryApi(api_client)

    # List all available advisory feeds (/v4/advisory)
    feeds: SearchV4ListFeedReturnValue = advisory_client.v4_list_advisory_feeds()
    print("Available feeds:")
    for feed in feeds.data:
        print(f"name: {feed.name}")

    feed = "wolfi"
    # Query advisories filtered by feed=wolfi (/v4/advisory?feed=wolfi)
    advisories: SearchV4AdvisoryReturnValue = advisory_client.v4_query_advisories(name=feed)
    print(f"{feed.capitalize()} advisories (page 1): {len(advisories.data)} results")
    for advisory in advisories.data:
        print(f"cve: {advisory.cve_metadata.cve_id}")
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio
from vulncheck_sdk.aio.models.search_v4_advisory_return_value import SearchV4AdvisoryReturnValue
from vulncheck_sdk.aio.models.search_v4_list_feed_return_value import SearchV4ListFeedReturnValue

TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def main():
    async with vcaio.ApiClient(configuration) as api_client:
        advisory_client = vcaio.AdvisoryApi(api_client)

        # List all available advisory feeds (/v4/advisory)
        feeds: SearchV4ListFeedReturnValue = await advisory_client.v4_list_advisory_feeds()
        print("Available feeds:")
        for feed in feeds.data:
            print(f"name: {feed.name}")

        feed = "wolfi"
        # Query advisories filtered by feed=wolfi (/v4/advisory?feed=wolfi)
        advisories: SearchV4AdvisoryReturnValue = await advisory_client.v4_query_advisories(name=feed)
        print(f"{feed.capitalize()} advisories (page 1): {len(advisories.data)} results")
        for advisory in advisories.data:
            print(f"cve: {advisory.cve_metadata.cve_id}")


if __name__ == "__main__":
    asyncio.run(main())

Backup

Download the backup for an index

import urllib.request
import vulncheck_sdk
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    index = "initial-access"

    api_response = endpoints_client.backup_index_get(index)

    file_path = f"{index}.zip"
    with urllib.request.urlopen(api_response.data[0].url) as response:
        with open(file_path, "wb") as file:
            file.write(response.read())
Click to View Async Implementation
import asyncio
import os
import urllib.request
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


def download_sync(url, file_path):
    """
    Standard synchronous download using urllib.request.
    This runs in a separate thread to avoid blocking the event loop.
    """
    with urllib.request.urlopen(url) as response:
        with open(file_path, "wb") as file:
            file.write(response.read())


async def main():
    # Use 'async with' to manage the connection life-cycle
    async with vcaio.ApiClient(configuration) as api_client:
        endpoints_client = vcaio.EndpointsApi(api_client)
        index = "initial-access"

        # 'await' the coroutine to get the actual response data
        api_response = await endpoints_client.backup_index_get(index)

        if not api_response.data:
            print("No backup URL found.")
            return

        download_url = api_response.data[0].url
        file_path = f"{index}.zip"

        print(f"Downloading {index} via urllib (offloaded to thread)...")

        # Use asyncio.to_thread to run the blocking call safely
        # 'await' the coroutine to get the actual response data
        await asyncio.to_thread(download_sync, download_url, file_path)

        print(f"Successfully saved to {file_path}")


if __name__ == "__main__":
    asyncio.run(main())

Backup v4

List available v4 backups and download a backup by feed name

import os
import tempfile
import urllib.request

from urllib3.util.retry import Retry

import vulncheck_sdk
from vulncheck_sdk.models.backup_backup_response import BackupBackupResponse
from vulncheck_sdk.models.backup_list_backups_response import BackupListBackupsResponse

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN
configuration.retries = Retry(
    total=5,
    backoff_factor=2,
    status_forcelist=[502, 503, 504],
    allowed_methods=["GET"],
    respect_retry_after_header=True,
)

with vulncheck_sdk.ApiClient(configuration) as api_client:
    backup_client = vulncheck_sdk.BackupApi(api_client)

    # List available backups (/v4/backup)
    available: BackupListBackupsResponse = backup_client.v4_list_backups()

    for potential_backup in available.data:
        print(f"Found backup: {potential_backup.name}")

    # Get backup for the wolfi feed (/v4/backup/wolfi)
    feed = "wolfi"
    response: BackupBackupResponse = backup_client.v4_get_backup_by_name(feed)

    print(response.to_json())

    print(f"Downloading {feed} backup")
    with tempfile.TemporaryDirectory() as tmpdir:
        file_path = os.path.join(tmpdir, f"{feed}.zip")
        with urllib.request.urlopen(response.url_mrap) as r:
            with open(file_path, "wb") as f:
                f.write(r.read())
        print(f"Successfully saved to {file_path}")
Click to View Async Implementation
import asyncio
import os
import tempfile
import urllib.request

import vulncheck_sdk.aio as vcaio
from vulncheck_sdk.aio.models.backup_backup_response import BackupBackupResponse
from vulncheck_sdk.aio.models.backup_list_backups_response import (
    BackupListBackupsResponse,
)

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN
configuration.retries = 5


def download_sync(url, file_path):
    """
    Standard synchronous download using urllib.request.
    This runs in a separate thread to avoid blocking the event loop.
    """
    with urllib.request.urlopen(url) as response:
        with open(file_path, "wb") as file:
            file.write(response.read())


async def main():
    async with vcaio.ApiClient(configuration) as api_client:
        backup_client = vcaio.BackupApi(api_client)

        # List available backups (/v4/backup)
        available: BackupListBackupsResponse = await backup_client.v4_list_backups()
        for potential_backup in available.data:
            print(f"Found backup: {potential_backup.name}")

        # Get backup for the wolfi feed (/v4/backup/wolfi)
        feed = "wolfi"
        response: BackupBackupResponse = await backup_client.v4_get_backup_by_name(feed)

        print(response.to_json())

        print(f"Downloading {feed} backup via urllib (offloaded to thread)...")
        with tempfile.TemporaryDirectory() as tmpdir:
            file_path = os.path.join(tmpdir, f"{feed}.zip")
            await asyncio.to_thread(download_sync, response.url_mrap, file_path)
            print(f"Successfully saved to {file_path}")


if __name__ == "__main__":
    asyncio.run(main())

CPE

Get all CPE's related to a CVE

import vulncheck_sdk
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    cpe = "cpe:/a:microsoft:internet_explorer:8.0.6001:beta"

    api_response = endpoints_client.cpe_get(cpe)

    for cve in api_response.data:
        print(cve)
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def get_cpe_vulnerabilities():
    # 'async with' to manage the connection life-cycle
    async with vcaio.ApiClient(configuration) as api_client:
        endpoints_client = vcaio.EndpointsApi(api_client)

        cpe = "cpe:/a:microsoft:internet_explorer:8.0.6001:beta"

        # 'await' the coroutine to get the actual response data
        api_response = await endpoints_client.cpe_get(cpe)

        # Iterate through the results
        if api_response.data:
            for cve in api_response.data:
                print(cve)
        else:
            print(f"No vulnerabilities found for CPE: {cpe}")


if __name__ == "__main__":
    # Run the main async entry point
    asyncio.run(get_cpe_vulnerabilities())

Index

Query VulnCheck-NVD2 for CVE-2019-19781

import vulncheck_sdk
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    indices_client = vulncheck_sdk.IndicesApi(api_client)

    api_response = indices_client.index_vulncheck_nvd2_get(cve="CVE-2019-19781")

    print(api_response.data)
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def get_cve_details():
    # Use 'async with' for the ApiClient
    async with vcaio.ApiClient(configuration) as api_client:
        indices_client = vcaio.IndicesApi(api_client)

        # 'await' the API call
        api_response = await indices_client.index_vulncheck_nvd2_get(
            cve="CVE-2019-19781"
        )

        # Access and print the data
        if api_response.data:
            print(api_response.data)
        else:
            print("No data found for the specified CVE.")


if __name__ == "__main__":
    # Start the async event loop
    asyncio.run(get_cve_details())

Indices

Get all available indices

import vulncheck_sdk
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    api_response = endpoints_client.index_get()

    for index in api_response.data:
        print(index.name)
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def list_indices():
    # Use 'async with' to manage the connection life-cycle
    async with vcaio.ApiClient(configuration) as api_client:
        endpoints_client = vcaio.EndpointsApi(api_client)

        # 'await' the coroutine to get the actual response
        api_response = await endpoints_client.index_get()

        # Iterate through the results
        if api_response.data:
            print(f"{'Index Name':<30} | {'Description'}")
            print("-" * 50)
            for index in api_response.data:
                print(f"{index.name:<30}")
        else:
            print("No indices found.")


if __name__ == "__main__":
    # 4. Entry point to run the asynchronous event loop
    asyncio.run(list_indices())

Pagination

Paginate over results for a query to VulnCheck-KEV using cursor

import vulncheck_sdk
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    indices_client = vulncheck_sdk.IndicesApi(api_client)
    api_response = indices_client.index_vulncheck_kev_get(
        start_cursor="true",
        # `limit` increases the size of each page, making it faster
        # to download large datasets
        limit=300,
    )

    print(api_response.data)

    while api_response.meta.next_cursor is not None:
        api_response = indices_client.index_vulncheck_kev_get(
            cursor=api_response.meta.next_cursor
        )
        print(api_response.data)
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def fetch_kev_data():
    # Use 'async with' to properly manage the lifecycle of the async client
    async with vcaio.ApiClient(configuration) as api_client:
        indices_client = vcaio.IndicesApi(api_client)

        # 'await' the coroutine to get the actual response data
        api_response = await indices_client.index_vulncheck_kev_get(
            start_cursor="true", limit=300
        )

        print(f"Fetched {len(api_response.data)} records...")
        # Process initial data
        # (e.g., save to a list or database)

        # Pagination loop
        while api_response.meta and api_response.meta.next_cursor:
            print(f"Fetching next page: {api_response.meta.next_cursor}")

            # 'await' the coroutine to get the actual response data
            api_response = await indices_client.index_vulncheck_kev_get(
                cursor=api_response.meta.next_cursor, limit=300
            )

            if api_response.data:
                print(f"Fetched {len(api_response.data)} records...")
            else:
                break


if __name__ == "__main__":
    # Entry point to run the async event loop
    asyncio.run(fetch_kev_data())

PURL

Get the CVE's for a given PURL

import vulncheck_sdk
from vulncheck_sdk.models.v3controllers_purl_response_data import (
    V3controllersPurlResponseData,
)
import os

TOKEN = os.environ["VULNCHECK_API_TOKEN"]

configuration = vulncheck_sdk.Configuration()
configuration.api_key["Bearer"] = TOKEN

with vulncheck_sdk.ApiClient(configuration) as api_client:
    endpoints_client = vulncheck_sdk.EndpointsApi(api_client)

    purl = "pkg:hex/coherence@0.1.2"

    api_response = endpoints_client.purl_get(purl)
    data: V3controllersPurlResponseData = api_response.data

    print(data.cves)
Click to View Async Implementation
import asyncio
import os
import vulncheck_sdk.aio as vcaio
from vulncheck_sdk.aio.models.v3controllers_purl_response_data import (
    V3controllersPurlResponseData,
)

# Configuration
TOKEN = os.environ.get("VULNCHECK_API_TOKEN")

configuration = vcaio.Configuration()
configuration.api_key["Bearer"] = TOKEN


async def get_data(client, purl: str):
    # Await the client call directly
    api_response = await client.purl_get(purl)

    # Access the data attribute from the response object
    return api_response.data


async def main():
    async with vcaio.ApiClient(configuration) as api_client:
        endpoints_client = vcaio.EndpointsApi(api_client)

        purl = "pkg:hex/coherence@0.1.2"

        # 'await' the async function call
        data: V3controllersPurlResponseData = await get_data(endpoints_client, purl)

        if data and data.cves:
            print(f"Found {len(data.cves)} CVEs:")
            for cve in data.cves:
                print(f"- {cve}")
        else:
            print("No CVEs found or data is empty.")


if __name__ == "__main__":
    asyncio.run(main())

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please create an issue.

Sponsorship

Development of this project is sponsored by VulnCheck learn more about us!

License

Apache License 2.0. Please see License File for more information.

Release files for vulncheck-sdk 0.0.54

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vulncheck-sdk 0.0.54
File Size Uploaded
vulncheck_sdk-0.0.54.tar.gz 1.8 MB Details

Built distribution (wheel)

Table of built distributions (wheels) for vulncheck-sdk 0.0.54
File Interpreter ABI Platform
vulncheck_sdk-0.0.54-py3-none-any.whl Python 3 none any Details

Total release size:7.5 MB

Release files / vulncheck_sdk-0.0.54.tar.gz

Download URL vulncheck_sdk-0.0.54.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
a90ecda672bf7635405e33d373702df204bf49a6adebf7980af39666d0934143
BLAKE2b-256 checksum
How to use checksums
83fe635849a81ebbd397a9d494c1b115a880354c685eaef074620793fa7f1dc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.

Transparency log

Release files / vulncheck_sdk-0.0.54-py3-none-any.whl

Download URL vulncheck_sdk-0.0.54-py3-none-any.whl
Size 5.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a2dfd35d5d32aef1f8d3cf35bb89e2d9ae4ee9cb29f915f3f3da2ace270a5ed5
BLAKE2b-256 checksum
How to use checksums
47bea0a89620b6fa212397e730b5257f246b9a8c3dc1479f409deb3968b032cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.

Transparency log

Release history Release notifications | RSS feed

0.1.0

2 release files

0.0.55

2 release files

This release

0.0.54 This release

2 release files

0.0.53

2 release files

0.0.51

2 release files

0.0.50

2 release files

0.0.49

2 release files

0.0.48

2 release files

0.0.47

2 release files

0.0.44

2 release files

0.0.43

2 release files

0.0.42

2 release files

0.0.41

2 release files

0.0.40

2 release files

0.0.39

2 release files

0.0.38

2 release files

0.0.37

2 release files

0.0.36

2 release files

0.0.33

2 release files

0.0.32

2 release files

0.0.31

2 release files

0.0.30

2 release files

0.0.29

2 release files

0.0.28

2 release files

0.0.27

2 release files

0.0.26

2 release files

0.0.25

2 release files

0.0.23

2 release files

0.0.20

2 release files

0.0.19

2 release files

0.0.17

2 release files

0.0.16

2 release files

0.0.15

2 release files

0.0.14

2 release files

0.0.13

2 release files

0.0.11

2 release files

0.0.10

2 release files

0.0.9

2 release files

0.0.8

2 release files

0.0.7

2 release files

0.0.6

2 release files

0.0.5

2 release files

0.0.4

2 release files

0.0.3

2 release files

0.0.2

2 release files

0.0.1

2 release 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