Skip to content

Partner Widget

<breachspider-check> puts the BreachSpider device check inside a partner's own portal. The partner's customers enter or paste their devices and get the same answer the API returns for each one: vulnerable at the installed version, still supported by the vendor, firmware current, each with its source. The widget is read only: it never changes a device and never stores device data.

Status: live. Widget keys are issued by BreachSpider on request.

How it works

  • One script, https://breachspider.com/widget/breachspider-check.js, adds the <breachspider-check> element.
  • Every check runs the same engine as Correlate CVEs. The widget is a presentation layer only.
  • The partner's secret API key never reaches the browser. The widget signs in with a publishable key or with a short-lived token that the partner's server mints.
  • Checks are billed to the partner's billing API key and logged per end customer under an opaque customer id the partner chooses. No names, emails or device lists are logged.

Quick start (publishable key)

<script src="https://breachspider.com/widget/breachspider-check.js" defer></script>
<breachspider-check widget-key="pk_live_..." heading="Device check"></breachspider-check>

A publishable key (pk_live_...) is not secret, by design:

  • it works only from the origins registered for it (exact match: scheme, host and port; no wildcards)
  • it works only on the widget endpoints
  • it checks at most 25 devices per request (or the key's own lower limit)
  • it is bound to one customer id, set when the key is issued

Register every origin that will show the widget before going live. A page on an unregistered origin gets no answer.

Signed token (server-side sign-in)

For a portal that already signs its users in, the partner's server mints a token for the signed-in customer and puts it on the page. Tokens allow up to 200 devices per request and expire after at most 15 minutes.

curl -X POST https://breachspider.com/api/widget/v1/token \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin": "https://portal.example.com", "customer_ref": "cust-1234", "ttl_seconds": 600}'
Field Rules
origin the page origin that will use the token; must be registered
customer_ref your opaque id for the end customer: 1 to 64 letters, digits, _ or -
ttl_seconds 60 to 900, default 600
frame true for the iframe embed without script (see below)

Response: token, expires_at (Unix time), origin, customer_ref. Mint tokens only from your server: the call needs your secret API key, which must never be sent to a browser.

<breachspider-check token="bswt1...." heading="Device check"></breachspider-check>

A token works only from the origin it was issued for, and stops working at once if that origin is removed or the billing key changes.

Attributes

Attribute Meaning
widget-key publishable key
token signed token (instead of widget-key)
heading title shown at the top
logo-url your logo: an HTTPS PNG, JPEG or WebP URL (SVG is not accepted)
bs-bg, bs-panel, bs-accent, bs-text, bs-muted, bs-border colors, hex only (for example #22C55E)
show-powered-by true (default) or false
show-json true shows "View JSON": the exact API response behind the screen
max-devices lower the device limit per check (never above the key's limit)
sample shows "Try a sample plant" (sample devices, live results)
endpoint API base; default is the origin the script was loaded from

Branding changes how the check looks, never what it returns: the request and the results are the same for every brand.

Iframe embed

For pages that cannot host a custom element (strict content policies, page builders), the same script can place the widget in an iframe served from breachspider.com:

<script src="https://breachspider.com/widget/breachspider-check.js" defer></script>
<div data-breachspider-check widget-key="pk_live_..." heading="Device check"></div>

The script asks for a short-lived frame session with the publishable key and hands it to the frame by message. The key never appears in a URL. The frame resizes to its content.

Without any script on the page, mint a token with "frame": true on your server and put it in the frame address fragment (never the query string). The frame reads it and removes it from its address.

<iframe src="https://breachspider.com/widget/frame.html#token=bswt1...." title="Device check"
        style="width:100%;border:0;min-height:480px"></iframe>

A frame token is accepted only from the registered page it was issued for.

What the end customer sees

  • Plant summary: devices checked, confirmed findings for the installed version, product-level findings, devices that need review, known-exploited findings, devices out of vendor support, devices with firmware behind, devices checked without a version.
  • Fix first: one entry per device: the single upgrade that closes all its version-fixable findings, ranked by the known-exploited list, then severity, then how many findings it closes.
  • No version given: a version is optional. Without one the card lists the product's known CVEs, the upgrade that clears the most of them, how many have no version fix, and the vendor's latest listed release where known.
  • Device card: the three answers, the one update that closes the most findings, and every finding with its source.
  • What changed: load a saved result, or check the result on screen again, and compare. Each device carries a result_hash (its findings) and a status_hash (known-exploited CVEs, lifecycle, firmware). The screen lists new and resolved findings, and status changes such as a CVE newly known-exploited, an end of life date published or a new firmware release. Results saved before 2026-10-27 have no status_hash; for them only findings are compared. A saved result is compared only under the widget key and plan it was made with (meta.compare_scope); a result from another key or plan is refused with a plain message, because its status answers were given for that caller.
  • Export: CSV (formula cells neutralized), a printable report, and the full JSON.
  • Data as of: when vulnerability, advisory and lifecycle data were last refreshed.

Nothing is ever shown as safe: a device with no findings is never called fixed or free of risk.

Windows hosts tab

Windows hosts have their own tab, so the device screens stay as they are. Each host is checked at its exact patch level against Microsoft's own security update data, by the same code as the API's stateless Windows check: CVEs open at the installed build, CVEs the build already fixes, CVEs that need review, and the update that closes them (for current Windows versions, the latest cumulative update).

Field Notes
Windows version Windows Server 2012 R2, 2016, 2019, 2022, 2025; Windows 10, Windows 11
Edition Server: Standard or Datacenter. Client: Pro, Enterprise, Enterprise LTSC, Education, Home
Installation Servers only: Server with Desktop or Server Core
Build The full build including its last part, for example 10.0.17763.5329 (winver, or ver in a command prompt)
Architecture x64 (default), arm64 or x86
Installed updates Optional KB numbers (Get-HotFix). Required for Windows Server 2012 R2, which is decided by its update list
Extended Security Updates Shown for Windows 10 and Server 2012 R2

Up to 25 hosts per check; a host counts like one device. A Windows host typed on the Devices tab gets a pointer to this tab with its version and build filled in. Host names are never sent: each host is identified by its position.

What changed works for Windows hosts too. Download the Windows summary page (or one host's page), then later load it on the Windows tab's What changed screen, or check the result on screen again. Each host carries the fields it was checked with (submitted) and a result_hash; the widget asks which hosts changed, checks only those again, and lists, per host, new and resolved open CVEs, a change in Microsoft support for that version, and a change in the CVEs cleared by installed updates. A Windows result downloaded before 2026-10-29 has no submitted fields and cannot be compared: check the hosts again and download the new result.

Endpoints

All under https://breachspider.com/api/widget/v1. The widget calls them for you. They are listed here for troubleshooting.

Method and path Sign-in Use
POST /check key or token device check; first page 25 findings per device, more on request
POST /changes key or token which devices changed since a saved result (by result_hash, and status_hash when sent)
POST /token your secret API key mint a token (server side only)
POST /frame-session publishable key frame token for the iframe embed
POST /check-windows key or token Windows hosts at patch level, up to 25; first page 25 open CVEs per host
POST /check-windows/changes key or token which Windows hosts changed since a saved result (each host's submitted fields and result_hash)
POST /suggest key or token "Did you mean" catalog names for devices that need review; not billed
GET /status none service status and data freshness

Usage and limits

  • Each device in /check uses the same units as a correlate-cves device. A "show more" page for a device already checked, and each device in /changes or host in /check-windows/changes, cost a tenth of that.
  • Usage rolls up from each customer id to the partner's monthly allowance. When it is used up, checks answer 429 QUOTA_EXCEEDED.
  • Rate limit: per partner, 30 checks per minute by default; above that 429 RATE_LIMITED (wait a minute).

Errors

Errors use the standard response format; the widget shows a plain message for each.

Status and code Meaning
401 WIDGET_AUTH_REQUIRED no key or token sent
401 WIDGET_KEY_INVALID unknown or revoked publishable key
401 WIDGET_TOKEN_INVALID / WIDGET_TOKEN_EXPIRED token not valid, or expired: mint a new one
403 WIDGET_ORIGIN the page's origin is not registered for this key or token
403 WIDGET_SAMPLE_ONLY the key checks the sample plant devices only
403 WIDGET_NOT_ENABLED / WIDGET_BILLING the widget is not enabled, or the billing key is not active
403 WIDGET_TOKEN_KEY_REQUIRED /token was called without your secret API key
409 WIDGET_SCOPE_MISMATCH "What changed": the saved result was made with a different widget key or plan; not billed
422 VALIDATION_ERROR / WIDGET_CUSTOMER request not valid, or customer_ref not in the allowed form
429 RATE_LIMITED / QUOTA_EXCEEDED too many checks in a minute, or the monthly allowance is used up
503 WIDGET_TOKEN_DISABLED token sign-in is not available; publishable keys still work

Warnings on each device result are the same as for Correlate CVEs, including VERSION_NOT_USED_FOR_RESOLUTION (a version such as R3.02.10 that cannot identify the product; it is still used for matching).