Skip to main content

BreachSpider Python SDK

Official Python client for the BreachSpider ICS/OT CVE intelligence API. Go from zero to working queries in about ten seconds from clone to first query (most of it pip install) instead of writing your own HTTP client.

  • Typed objects for CVEs, vendors, products, environments, and assets, not raw dicts.
  • Transparent pagination that absorbs the API's per-endpoint shapes.
  • Automatic 429 backoff so a naive loop over thousands of CVEs won't trip the edge limit.
  • Typed exceptions that surface the API's own helpful error messages.
  • The API key is never printed, logged, or included in an exception.
  • New in 0.3.0: cited source references on every CVE: vendor advisories, government ICS advisories and the CVE.org record. See the changelog.
  • New in 0.2.0: asset correlation (API v1) and Windows patch level (API v2), with the exposure-priority ranking, fix groups and fix plans. See the changelog: the API's default CVE order changed to priority.

Install

pip install breachspider

Requires Python 3.9+. The only dependency is requests.

60-second quickstart (no signup)

Client.demo() mints a read-only demo token (valid 24h, scoped to a public demo org). No API key or signup required.

import breachspider

bs = breachspider.Client.demo()

# Find a vendor. Read the slug from the response, never hand-craft it.
vendor = bs.catalog.vendor("schneider electric")
print(vendor.id, vendor.name, vendor.slug)   # 11529 Schneider-Electric schneider-electric

# List that vendor's products, each with a CVE count.
for product in bs.catalog.products(vendor_id=vendor.id)[:3]:
    print(f"  {product.id:>6}  {product.name}  ({product.cve_count} CVEs)")

# Critical, known-exploited CVEs for that vendor.
for cve in bs.cves.by_vendor(vendor.slug, severity="CRITICAL", kev=True):
    print(cve.cve_id, "-", cve.title)
    break   # (the loop would page through all of them)

Authentication

Use a real API key (bs_live_…) for production. Start a free trial key at breachspider.com/developers, or ask about partner keys through "Talk to us" on the same page. Organizations with dashboard access can also create keys under Integrations → API Keys.

import os
import breachspider

# export BREACHSPIDER_API_KEY=bs_live_your_key_here
bs = breachspider.Client(os.environ.get("BREACHSPIDER_API_KEY", "bs_live_YOUR_KEY_HERE"))
print(bs)   # key is redacted: <breachspider.Client base_url='https://breachspider.com' auth=live key=***redacted***>

The key is held privately: it never appears in repr(), str(), logs, or any exception message.

The primary workflow: vendor → products → CVEs

import breachspider

bs = breachspider.Client.demo()

vendor = bs.catalog.vendor("schneider electric")
assert (vendor.id, vendor.slug) == (11529, "schneider-electric")

products = bs.catalog.products(vendor_id=vendor.id)
m340 = next(p for p in products if p.id == 25001)
print(m340.name, m340.cve_count)          # Modicon M340 41

# by_vendor takes the slug and supports the full /cves filter set.
criticals = bs.cves.by_vendor(vendor.slug, severity="CRITICAL", kev=True)
first = next(iter(criticals))
print(first.cve_id, first.severity, first.cvss_score, first.kev_flagged)

Searching CVEs

bs.cves.search(**filters) returns an iterator that transparently follows pages. Accepted filters:

q, vendor (slug), protocol, severity, kev, unpatched, has_exploit, patch_status, cvss_min, cvss_max, bcs_min, bcs_max, date_from, date_to, sort_by, ranked.

There is no product, version, or cpe filter on /cves today. To narrow to a product, filter by vendor and match on the result fields.

cves.search works with a demo token (as below) or a partner or customer key. A trial key cannot call it (TRIAL_SCOPE); trial keys can correlate devices and look up single CVEs with bs.cves.get.

import itertools
import breachspider

bs = breachspider.Client.demo()

# First 5 known-exploited CVEs affecting Siemens, highest CVSS first.
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)

# One CVE by id (rich detail; nested scoring/exploitation/patch in .raw).
cve = bs.cves.get("CVE-2025-32433")
print(cve.cve_id, cve.severity, cve.cvss_score, cve.html_url)

Pagination

Every search/by_vendor/assets call is a lazy iterator: it fetches the next page only as you consume it, and stops at the end. Page size defaults to 100 (the maximum). Different endpoints paginate differently (per_page vs limit, _links.next vs page numbers vs offset); the SDK handles all of them.

import breachspider

bs = breachspider.Client.demo()

count = 0
for _cve in bs.cves.search(vendor="schneider-electric"):
    count += 1
    if count >= 250:      # 250 spans 3 pages of 100; the SDK paged for you
        break
print("iterated", count, "CVEs across multiple pages")

Do not call list() on a search iterator

list(bs.cves.search(...)) materializes every page of the result set. Siemens alone has over 5,000 CVEs; walking all of them will exhaust every page and can trigger the rate limit. Use itertools.islice when you only need the first N, or a for loop with a break.

import itertools
import breachspider

bs = breachspider.Client.demo()

# Safe: fetch exactly 10 results and stop. Never touches page 2 or beyond.
first_ten = list(itertools.islice(
    bs.cves.search(vendor="siemens", kev=True, sort_by="cvss"), 10))
for cve in first_ten:
    print(cve.cve_id, cve.cvss_score)

Rate-limit safety

The API sits behind a Cloudflare edge limit that trips at roughly 37 rapid requests from one IP. The client sleeps page_delay seconds (default 0.25) between pages and retries any 429 with exponential backoff. Tune it:

import breachspider

# Faster (riskier) or gentler pagination, and more patient retries.
bs = breachspider.Client.demo(page_delay=0.5, max_retries=8, backoff_factor=1.0)
print("page_delay:", bs.page_delay, "max_retries:", bs.max_retries)

Quota / usage headers

With a demo token (Client.demo()), bs.quota is always None; demo traffic is not metered.

With a bs_live_ key, every response carries X-RateLimit-* headers that the client parses into bs.quota after any call. Metering is observe-only today: usage is reported but nothing is rejected. Unlimited tiers report the string "unlimited".

import os
import breachspider
from breachspider import AuthenticationError

# export BREACHSPIDER_API_KEY=bs_live_your_key_here
bs = breachspider.Client(os.environ.get("BREACHSPIDER_API_KEY", "bs_live_YOUR_KEY_HERE"))

try:
    # Correlate works with every key type, including trial keys.
    device = {"asset_id": "asset-1", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5"}
    bs.correlate.correlate([device])
    q = bs.quota
    print("limit:", q.limit, "used:", q.used, "remaining:", q.remaining)
    # limit is your key's allowance, or 'unlimited'
except AuthenticationError:
    print("Set BREACHSPIDER_API_KEY to a live bs_live_… key to see quota.")

Error handling

Errors map to typed exceptions that keep the server's own message and structured detail, the most useful part.

import breachspider
from breachspider import UnknownParameterError, ValidationError, NotFoundError

bs = breachspider.Client.demo()

# 400 UNKNOWN_PARAMETER surfaces the accepted-parameter list.
try:
    list(bs.cves.search(color="red"))
except UnknownParameterError as e:
    print("accepted:", e.accepted_parameters)

# 422 for per_page > 100 (the real per-page maximum is 100 on every tier).
try:
    bs.request("GET", "/cves", params={"per_page": 101})
except ValidationError as e:
    print("validation:", e.fields)

# 404 for a CVE that doesn't exist.
try:
    bs.cves.get("CVE-0000-00000")
except NotFoundError as e:
    print("not found:", e.message)
Exception HTTP Notable attributes
UnknownParameterError 400 accepted_parameters, unknown_parameters
AuthenticationError 401
InsufficientScopeError 403 required_scope, current_scopes
CapExceededError 403 resource, limit, current, tier
NotFoundError 404 detail
ValidationError 422 fields
RateLimitError 429 retry_after (auto-retried first)

All inherit from breachspider.BreachSpiderError. Network failures raise APIConnectionError (never leaking the request or key).

Correlate assets (API v1)

Send your inventory (vendor, product, version); get each asset's CVEs ranked by what's exposed and what to fix first, the fix actions, and a fix plan. Nothing is stored server-side.

device = {"asset_id": "EXAMPLE-SWITCH-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5"}
resp = bs.correlate.correlate([device])          # sort="priority" by default; also "score", "exploit", "newest"
result = resp.results[0]
for cve in result.cves:
    print(cve.priority_rank, cve.cve_id, cve.priority_reason)
print(result.fix_groups[0].fix, result.fix_plan)
every_page = bs.correlate.all_cves(device)       # follows cves_page.has_more for you

Filters: confirmed_only, known_exploited_only, fix_available_only. result_hash never depends on sort, filters or page; use bs.correlate.check(...) to re-correlate only what changed. Guide: docs/correlate.md.

Windows patch level (API v2)

Send Windows build and KB facts; get confirmed open / cleared / needs review per CVE from Microsoft's own data, with fix actions such as "install KB5122876 (latest cumulative, build 10.0.17763.9245)". Submitting needs a write-scoped key.

hosts = [{"asset_id": "WIN-EXAMPLE-01", "os_product": "Windows Server 2019 Standard", "edition_id": "ServerStandard",
          "os_build": "10.0.17763.7792", "architecture": "x64", "installation_type": "Server",
          "collected_at": "2026-09-25T14:02:00Z"}]
resp = bs.windows.correlate(12, hosts, include_cleared=False)
for r in resp.rejected:                          # refused hosts (e.g. an identifying field); nothing stored
    print(r.asset_id, r.error_codes)
for batch in bs.windows.correlate_batched(12, many_hosts):   # calls of 25 hosts (the per-call limit)
    ...
bs.windows.correlate_csv(12, "hosts.csv")        # the same from a CSV file
bs.windows.results(12, asset_id="WIN-EXAMPLE-01", cve_page_size=50)

Check Windows hosts without storing anything

bs.windows.check() gives the same per-CVE decisions as correlate() (confirmed open, cleared or needs review, with the fixed build, KB and Microsoft source), but nothing about the hosts is saved and no environment is needed. Any API key works, read-only included. Trial keys, demo tokens and browser sessions are refused.

hosts = [{"asset_id": "asset-1", "os_product": "Windows Server 2019 Standard", "edition_id": "ServerStandard",
          "os_build": "10.0.17763.7792", "architecture": "x64", "installation_type": "Server",
          "collected_at": "2026-09-25T14:02:00Z"}]
resp = bs.windows.check(hosts, include_cleared=False)    # at most 25 hosts per call
resp.stored                                              # False: nothing was saved
host = resp.assets[0]
host.counts, host.cves[0].status, host.result_hash
for batch in bs.windows.check_batched(many_hosts):       # calls of 25
    ...
# Later: learn cheaply which hosts changed (up to 200 per call, about a tenth of the cost)
changes = bs.windows.check_changes([{**hosts[0], "result_hash": host.result_hash}])
changes.changed                                          # asset_ids to check again

Identifying fields (host name, IP or MAC address, user and similar) are refused, and so is an asset_id shaped like an IP, MAC or email address or a domain name. Your own asset tags, such as PLC-LINE-2, are fine.

Guide: docs/windows-v2.md. Examples for every endpoint: examples/. OpenAPI document for these endpoints: openapi/breachspider-openapi.json.

Writes

Reads work with any key. Writes (environments.create, environments.add_asset, watchlist.add, environments.create_ticket, reports.generate) require a write-scoped bs_live_ key and are rejected for demo tokens. Session-only operations (API-key management, webhook delivery, billing, and account settings) are intentionally not part of this SDK; they can never be called with a key.

Honest limits

  • Per page: 100 results maximum on every paid tier (10 on Free). There is no pagination depth cap; you can page through the entire result set.
  • No product/version/CPE filter on /cves yet. Filter by vendor (slug).
  • Metering is observe-only. Usage is counted and returned in headers, but no request is rejected for exceeding a monthly allowance today.

Running the tests

Install the dev extras, then run the suite:

pip install ".[dev]"
pytest

The suite includes live integration tests that hit the real API using a demo token. To skip them when offline (or in CI without network access):

BREACHSPIDER_SKIP_INTEGRATION=1 pytest

The integration tests are marked @pytest.mark.integration and are skipped automatically if the API is unreachable or the env var is set. The correlate and Windows tests run against responses recorded from the live API (tests/fixtures/), so they need no key and no network.

License

MIT © CITED Relevance LLC

Metadata

Release files for breachspider 0.3.1

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

Source distribution (sdist)

Source distribution for breachspider 0.3.1
File Size Uploaded Provenance Actions
breachspider-0.3.1.tar.gz 41.1 kB With provenance Details for breachspider-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for breachspider 0.3.1
File Interpreter ABI Platform Actions
breachspider-0.3.1-py3-none-any.whl Python 3 none any Details for breachspider-0.3.1-py3-none-any.whl

Total release size: 74.6 kB

Release files / breachspider-0.3.1.tar.gz

Download URL breachspider-0.3.1.tar.gz
Size 41.1 kB
Tags Source
SHA-256 checksum
How to use checksums
eb64c573207248d6c822e911333147e8e74d4b087d9621743ffa377aa7e9ca3f
BLAKE2b-256 checksum
How to use checksums
9da6dbabfb4a314b6a1101175554bb0ef68374ecf7d582c9f1f1bd01650317b4
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 Oct 1, 2026.

Transparency log

Release files / breachspider-0.3.1-py3-none-any.whl

Download URL breachspider-0.3.1-py3-none-any.whl
Size 33.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
19900b6d1bc079fd9723ca772157e8737d5dc8fcf8275c2ecc99cd02f80405e3
BLAKE2b-256 checksum
How to use checksums
68ba97fe5e908d6e0cfc723bdf86ac952185ad39754f46733b844d0fbf1f2e15
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 Oct 1, 2026.

Transparency log

Security for breachspider 0.3.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for breachspider-0.3.1.tar.gz

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 Oct 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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