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 astatus_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 nostatus_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
/checkuses the same units as a correlate-cves device. A "show more" page for a device already checked, and each device in/changesor 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).