Skip to content

Python SDK

The official Python client for the BreachSpider API: typed results, paging handled for you, retries that follow the API's own retry guidance, and an API key that never appears in a log, repr() or exception.

pip install breachspider

Package breachspider on PyPI, version 0.4.0 (November 2026). Python 3.9 or newer; the only dependency is requests. MIT licensed.

Try it without a key

Client.demo() gets a read-only demo token for public example data (valid 24 hours). No signup. Device checks in demo mode cover six example devices: Moxa EDS-518A V3.5, Siemens SCALANCE XC208 V4.2.0, Siemens SCALANCE X200 5.2.0, Rockwell Automation 1756-EN2TR Series C 11.002, Schneider Electric EGX150/Link150 Ethernet Gateway 5.0.24 and ABB AC500 CPU Firmware 3.8.0. Any other device returns DEMO_EXAMPLES_ONLY.

import breachspider

bs = breachspider.Client.demo()
resp = bs.correlate.correlate([{"asset_id": "SW-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5"}])
result = resp.results[0]
for cve in result.cves:
    print(cve.priority_rank, cve.cve_id, cve.match_tier, cve.priority_reason)
print(result.fix_plan)

On 2026-11-08 this prints three CVEs (CVE-2024-9137, CVE-2024-9404, CVE-2024-7695), all RANGE matches, and a fix plan of "upgrade to security patch 3.11.2" from Moxa advisory MPSA-241156.

Use your key

import os
import breachspider

# export BREACHSPIDER_API_KEY=bs_live_...
bs = breachspider.Client(os.environ["BREACHSPIDER_API_KEY"])
print(bs)   # the key is shown as ***redacted***

Keys: Integrations in the web app, a free trial key at breachspider.com/developers, or a partner key from us.

Check devices (API v1)

devices = [
    {"asset_id": "SW-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5"},
    {"asset_id": "SW-02", "vendor": "Siemens", "product": "SCALANCE XC208", "version": "V4.2.0"},
]
resp = bs.correlate.correlate(devices)          # sort="priority" by default; also "score", "exploit", "newest"
for r in resp.results:
    print(r.asset_id, len(r.cves), r.result_hash)
    if r.fix_groups:
        print("  first action:", r.fix_groups[0].fix)
every_cve = bs.correlate.all_cves(devices[0])   # follows cves_page.has_more for you

Filters: confirmed_only, known_exploited_only, fix_available_only. Keep result_hash (and status_hash) per device and later call bs.correlate.check(...) to learn cheaply which devices changed. Details: Correlate CVEs.

Windows hosts

hosts = [{"asset_id": "WIN-01", "os_product": "Windows Server 2019 Standard", "edition_id": "ServerStandard",
          "os_build": "10.0.17763.7792", "architecture": "x64", "installation_type": "Server",
          "collected_at": "2026-11-01T14:02:00Z"}]
resp = bs.windows.check(hosts, include_cleared=False)   # stores nothing; at most 25 hosts per call
host = resp.assets[0]
print(host.counts, host.result_hash)

bs.windows.check() needs a partner or customer key (trial keys and demo tokens are refused). To keep hosts in an environment with history, use bs.windows.correlate(environment_id, hosts) with a write key. See Windows patch level.

Batch jobs

For more than 200 devices at once, on keys with batch jobs enabled:

job = bs.batches.submit(devices)         # up to 5,000 devices; kind="windows_hosts" for up to 1,000 hosts
job = bs.batches.wait(job)               # polls with back-off until it finishes
for item in bs.batches.results(job):
    if item["state"] == "done":
        print(item["result"]["asset_id"], item["result"]["result_hash"])

Resubmitting the same body with the same idempotency_key within 24 hours returns the original job, so a retry never charges twice.

import itertools

for cve in itertools.islice(bs.cves.search(vendor="siemens", kev=True, sort_by="cvss"), 5):
    print(cve.cve_id, cve.cvss_score, cve.severity)
cve = bs.cves.get("CVE-2024-9137")

Searches are lazy iterators: use itertools.islice or break, never list() on a large search. Trial keys can look up single CVEs but not search.

Errors and retries

Every exception carries the API's retry guidance: retryable, retry_after_seconds, action (retry_later, wait_until_reset, reduce_batch, fix_input, use_different_key, contact_us) and reset_at. The client already retries what is retryable and never retries what is not. Typed exceptions include AuthenticationError, ScopeError, TrialEndedError, BatchTooLargeError, ValidationError, RateLimitError and UsageLimitError. See Errors and retry guidance.

Source and changelog

The full README, examples and changelog are on the PyPI page.