Correlate CVEs (stateless)¶
Send a list of assets (vendor, product, version) and get back, for each one, the catalog product it resolved to, how confident that resolution is, and the CVEs that affect it. Nothing is stored: use these calls to check an inventory held in your own system. To keep findings in BreachSpider, add the assets to an environment instead (see Assets).
| Method and path | Purpose |
|---|---|
POST /api/v1/assets/correlate-cves | Resolve and correlate up to 200 assets |
POST /api/v1/assets/correlate-cves/check | Cheap staleness check: has the result for an asset changed since you last fetched it? |
Auth: any API key (Authorization: Bearer bs_live_...). A read-only key is enough; no write scope is needed. Expired or revoked keys get 401.
Limits: at most 200 assets per call (413 BATCH_TOO_LARGE). Per API key: 60 requests and 5,000 assets per minute by default, shared with API v2; over the limit you get 429 with retry_after (seconds). Ask us for a temporary higher limit for an initial bulk load.
Time per call: the server recomputes every distinct device (identical devices in one call are computed once): about 0.2 s per distinct device for /check and more for a full correlation, so 200 distinct devices on /check take about 40 seconds. Set your client timeout to at least 90 seconds for these two endpoints (the SDK and the MCP server do; requests are cut at 100 seconds). If a call times out, do not resend it unchanged: split it into batches of at most 50.
For Windows hosts where you know the full build and installed KBs, use Windows Patch Level (API v2): it returns confirmed open / cleared per CVE from Microsoft's own fixed builds. This endpoint matches Windows at product level only.
The response shape is a frozen v1 contract. New fields and new warning codes may be added; existing fields are never renamed, retyped or removed. Ignore keys you don't know.
Request¶
| Field | Required | Meaning |
|---|---|---|
assets[].asset_id | yes | Your identifier, echoed back. At most 64 characters. An IP address, MAC address, fully qualified hostname or email address is refused with 422. |
assets[].vendor | yes | Vendor name as you hold it (free text) |
assets[].product | yes | Product or model (free text; vendor order codes are recognised for common OT vendors) |
assets[].version | no | Software or firmware version used for matching. Without any version, matches are product-level and flagged. |
assets[].firmware_version | no | Firmware version. Used for matching only when version is empty (the result then carries VERSION_FROM_FIRMWARE). |
assets[].product_type | no | Hint such as PLC, HMI, Server |
assets[].part_number | no | The device's vendor part, order or model number when you hold it separately from the product name (for example IR809G-LTE-VZ-K9, 3623-072202, 6ES7315-2EH14-0AB0). At most 100 characters. It is matched exactly against vendor part numbers for lifecycle and firmware answers, and used to identify the product only when the product text does not resolve (PART_NUMBER_RESOLVED). |
options.min_confidence | no | LOW, MEDIUM (default) or HIGH: resolutions below this band return no CVEs and are flagged needs_review |
options.include_capec | no | Adds MITRE CAPEC attack patterns to each CVE. Default false for API keys (true in the web app). |
options.cve_page | no | Page of each asset's CVE list to return (default 1) |
options.cve_page_size | no | CVEs per asset per page, 1–1000. Default 250 for API keys (all CVEs in the web app). |
options.sort | no | Order of each asset's cves[]: priority (default), score, exploit or newest (see Ranking). Any other value returns 422. |
options.confirmed_only | no | Only CVEs confirmed for the supplied version (EXACT or RANGE). Default false. |
options.known_exploited_only | no | Only CVEs on the CISA Known Exploited Vulnerabilities catalog. Default false. |
options.fix_available_only | no | Only CVEs with a known fix (stored, derived, or ESU). Default false. |
Sorting and filters are applied before paging, so page 1 always holds the highest priorities and cves_page.total is the filtered count. result_hash always fingerprints the full, unfiltered result, whatever the sort, filters or page.
Example (real call)¶
A public example device: a Moxa EDS-518A switch on firmware V3.5. The response below is exactly what the API returned on 2026-09-26, except that cves is shortened to 2 of the 3 CVEs (cves_page.total still shows 3).
curl -X POST https://breachspider.com/api/v1/assets/correlate-cves \
-H "Authorization: Bearer bs_live_..." \
-H "Content-Type: application/json" \
-d '{"assets": [{"asset_id": "EXAMPLE-SWITCH-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5"}]}'
{
"api": {
"version": "1.0.0",
"request_id": "bs-req-dfe090267833",
"timestamp": "2026-09-26T17:21:56.022398Z",
"processing_ms": 217
},
"data": {
"results": [
{
"asset_id": "EXAMPLE-SWITCH-01",
"submitted": {
"vendor": "Moxa",
"product": "EDS-518A",
"version": "V3.5",
"firmware_version": null,
"product_type": null,
"part_number": null
},
"resolution": {
"status": "resolved",
"coverage": "covered",
"confidence": 94,
"confidence_band": "HIGH",
"vendor": {
"id": 11418,
"name": "Moxa",
"slug": "moxa"
},
"product": {
"id": 178012,
"name": "EDS-518A",
"slug": "eds-518a"
},
"cpe": {
"vendor": "moxa",
"product": "eds-518a"
},
"match_basis": [
"cpe_alias",
"exact",
"prefix",
"substring",
"token",
"version:in_range"
]
},
"candidates": [],
"cves": [
{
"cve_id": "CVE-2024-9137",
"bsid": "BS-2024-GLOBAL-046494-C",
"title": "The affected product lacks an authentication check when sending commands to the server via the Moxa service. This vulner",
"description": "The affected product lacks an authentication check when sending commands to the server via the Moxa service. This vulnerability allows an attacker to execute specified commands, potentially leading to unauthorized downloads or uploads of configuration files and system compromise.",
"scoring": {
"cvss": {
"score": 9.4,
"vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:H/A:H",
"version": "3.1",
"severity": "CRITICAL",
"attack_vector": "NETWORK",
"attack_complexity": "LOW",
"privileges_required": "NONE",
"user_interaction": "NONE",
"scope": "UNCHANGED",
"confidentiality_impact": "LOW",
"integrity_impact": "HIGH",
"availability_impact": "HIGH"
},
"epss": {
"score": 0.00501,
"percentile": 0.4034,
"interpretation": "Below median exploitation probability"
},
"bcs": null
},
"exploitation": {
"kev_flagged": false,
"kev_added_at": null,
"has_public_exploit": false,
"poc_available": false,
"exploit_maturity": "NONE",
"actively_exploited": false
},
"affected": {
"vendors": [
"Moxa"
],
"products": [],
"primary_vendor": null,
"primary_product": null,
"vendor_count": 1,
"device_types": [
"Industrial Firewall"
],
"protocols": [],
"ics_relevance_score": 0.7,
"ics_relevant": true
},
"patch": {
"status": "unknown",
"patch_available": false,
"patch_version": null,
"patch_url": null,
"patch_notes": null
},
"classification": {
"cwes": [
{
"id": 306,
"url": "https://cwe.mitre.org/data/definitions/306.html"
}
],
"attack_vector": "NETWORK",
"attack_complexity": "LOW",
"privileges_required": "NONE",
"user_interaction": "NONE",
"scope": "UNCHANGED",
"layer": null,
"category": null
},
"sage": {
"model": "SAGE-v1",
"tier": "full",
"executive_summary": "CVE-2024-9137 affects Moxa products due to a lack of authentication checks when sending commands to the server via the Moxa service. This can lead to unauthorized command execution, potentially allowing attackers to download or upload configuration files and compromise the system. The CVSS score is 9.4, indicating a high severity level.",
"ics_context": null,
"remediation_guidance": null,
"confidence_score": null,
"confidence_tier": null,
"_upgrade_required": false,
"_upgrade_url": null
},
"temporal": {
"published_at": "2024-10-14T09:15:04+00:00",
"modified_at": "2026-06-17T08:24:01+00:00",
"enriched_at": "2026-05-22T15:36:48.504598+00:00",
"kev_added_at": null
},
"references": {
"nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2024-9137",
"cisa_url": null,
"breachspider_url": "https://breachspider.com/ics-cve/CVE-2024-9137",
"vendor_advisories": [
{
"url": "https://www.moxa.com/en/support/product-support/security-advisory/mpsa-241154-missing-authentication-and-os-command-injection-vulnerabilities-in-routers-and-network-security-appliances",
"title": null,
"source": "vendor_cna"
},
{
"url": "https://www.moxa.com/en/support/product-support/security-advisory/mpsa-241156-cve-2024-9137-missing-authentication-vulnerability-in-ethernet-switches",
"title": null,
"source": "vendor_cna"
}
],
"cve_org_url": "https://www.cve.org/CVERecord?id=CVE-2024-9137",
"other_references": [],
"other_references_total": 0,
"cisa_ics_advisories": [],
"cited_exclusive": null
},
"_links": {
"self": "/api/v1/cves/CVE-2024-9137",
"pdf": "/api/v1/ics-cve/CVE-2024-9137/pdf",
"html": "https://breachspider.com/ics-cve/CVE-2024-9137"
},
"match_tier": "RANGE",
"affected_range": {
"cpe_version": "*",
"is_range": true,
"version_start": "1.0",
"version_start_inclusive": true,
"version_end": "3.11",
"version_end_inclusive": true
},
"priority_rank": 1,
"priority_reason": "confirmed (affected 1.0 to 3.11), fix: upgrade beyond 3.11 (derived)",
"fix": {
"available": true,
"action": "upgrade beyond 3.11",
"source": "derived",
"derived": true
}
},
{
"cve_id": "CVE-2024-7695",
"bsid": "BS-2025-GLOBAL-043371-H",
"title": "Multiple switches are affected by an out-of-bounds write vulnerability. This vulnerability is caused by insufficient inp",
"description": "Multiple switches are affected by an out-of-bounds write vulnerability. This vulnerability is caused by insufficient input validation, which allows data to be written to memory outside the bounds of the buffer. Successful exploitation of this vulnerability could result in a denial-of-service attack.",
"scoring": {
"cvss": {
"score": 7.5,
"vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
"version": "3.1",
"severity": "HIGH",
"attack_vector": "NETWORK",
"attack_complexity": "LOW",
"privileges_required": "NONE",
"user_interaction": "NONE",
"scope": "UNCHANGED",
"confidentiality_impact": "NONE",
"integrity_impact": "NONE",
"availability_impact": "HIGH"
},
"epss": {
"score": 0.00728,
"percentile": 0.52206,
"interpretation": "Above median exploitation probability"
},
"bcs": null
},
"exploitation": {
"kev_flagged": false,
"kev_added_at": null,
"has_public_exploit": false,
"poc_available": false,
"exploit_maturity": "NONE",
"actively_exploited": false
},
"affected": {
"vendors": [],
"products": [],
"primary_vendor": null,
"primary_product": null,
"vendor_count": 0,
"device_types": [],
"protocols": [],
"ics_relevance_score": 0.15,
"ics_relevant": false
},
"patch": {
"status": "unknown",
"patch_available": false,
"patch_version": null,
"patch_url": null,
"patch_notes": null
},
"classification": {
"cwes": [
{
"id": 787,
"url": "https://cwe.mitre.org/data/definitions/787.html"
}
],
"attack_vector": "NETWORK",
"attack_complexity": "LOW",
"privileges_required": "NONE",
"user_interaction": "NONE",
"scope": "UNCHANGED",
"layer": null,
"category": null
},
"sage": {
"model": "SAGE-v1",
"tier": "full",
"executive_summary": "Multiple switches are affected by an out-of-bounds write vulnerability due to insufficient input validation, which could lead to a denial-of-service attack.",
"ics_context": null,
"remediation_guidance": null,
"confidence_score": null,
"confidence_tier": null,
"_upgrade_required": false,
"_upgrade_url": null
},
"temporal": {
"published_at": "2025-01-29T08:15:19+00:00",
"modified_at": "2026-06-17T08:20:44+00:00",
"enriched_at": "2026-05-22T15:36:41.240464+00:00",
"kev_added_at": null
},
"references": {
"nvd_url": "https://nvd.nist.gov/vuln/detail/CVE-2024-7695",
"cisa_url": null,
"breachspider_url": "https://breachspider.com/ics-cve/CVE-2024-7695",
"vendor_advisories": [
{
"url": "https://www.moxa.com/en/support/product-support/security-advisory/mpsa-240162-cve-2024-7695-out-of-bounds-write-vulnerability-identified-in-multiple-pt-switches",
"title": null,
"source": "vendor_cna"
},
{
"url": "https://www.moxa.com/en/support/product-support/security-advisory/mpsa-240163-cve-2024-7695-out-of-bounds-write-vulnerability-in-multiple-eds,-ics,-iks,-and-sds-switches",
"title": null,
"source": "vendor_cna"
},
{
"url": "https://www.moxa.com/en/support/product-support/security-advisory/mpsa-240164-cve-2024-7695-out-of-bounds-write-vulnerability-identified-in-en-50155-switches",
"title": null,
"source": "vendor_cna"
}
],
"cve_org_url": "https://www.cve.org/CVERecord?id=CVE-2024-7695",
"other_references": [],
"other_references_total": 0,
"cisa_ics_advisories": [],
"cited_exclusive": null
},
"_links": {
"self": "/api/v1/cves/CVE-2024-7695",
"pdf": "/api/v1/ics-cve/CVE-2024-7695/pdf",
"html": "https://breachspider.com/ics-cve/CVE-2024-7695"
},
"match_tier": "RANGE",
"affected_range": {
"cpe_version": "*",
"is_range": true,
"version_start": "1.0",
"version_start_inclusive": true,
"version_end": "3.11",
"version_end_inclusive": true
},
"priority_rank": 2,
"priority_reason": "confirmed (affected 1.0 to 3.11), fix: upgrade beyond 3.11 (derived)",
"fix": {
"available": true,
"action": "upgrade beyond 3.11",
"source": "derived",
"derived": true
}
}
],
"cves_page": {
"page": 1,
"page_size": 250,
"total": 3,
"total_unfiltered": 3,
"has_more": false
},
"fix_groups": [
{
"fix": "upgrade beyond 3.11",
"fix_type": "version",
"source": "derived",
"derived": true,
"cve_ids": [
"CVE-2024-9137",
"CVE-2024-7695",
"CVE-2024-9404"
],
"counts": {
"total": 3,
"confirmed": 3,
"known_exploited": 0,
"exploit_available": 0
},
"highest_score": {
"bcs": 6.84,
"cvss": 9.4
},
"group_rank": 1
}
],
"fix_plan": {
"to_clear_known_exploited": null,
"to_clear_all_fixable": {
"fix": "upgrade beyond 3.11",
"derived": true,
"source": "derived",
"clears": {
"cves": 3,
"known_exploited": 0,
"groups": 1
},
"note": "Derived from affected version ranges, not from a vendor fix statement. Confirm the target release in the vendor's advisory: that release may not exist in this product line."
}
},
"needs_review": false,
"correlated_at": "2026-09-26T17:21:56.022015+00:00",
"result_hash": "sha256:ee5e58d4b621d3ce37f9f3df9b924b0cfa7006e2323daefd1d6f2b84c561756a",
"warnings": []
}
],
"summary": {
"total": 1,
"by_status": {
"resolved": 1,
"ambiguous": 0,
"unresolved": 0
},
"by_coverage": {
"covered": 1,
"no_cpe_data": 0,
"partial": 0,
"null": 0
}
},
"fix_summary": [
{
"rank": 1,
"fix": "upgrade beyond 3.11",
"product": "EDS-518A",
"fix_type": "version",
"source": "derived",
"derived": true,
"asset_ids": [
"EXAMPLE-SWITCH-01"
],
"counts": {
"assets": 1,
"cves": 3,
"known_exploited": 0,
"exploit_available": 0,
"confirmed": 3
},
"highest_score": {
"bcs": 6.84,
"cvss": 9.4
}
}
]
},
"meta": {
"source": "breachspider-correlate",
"matcher": "stateless; same version-range rules as stored matching, without the stored product-level and vendor-only fallbacks (reported as coverage and warnings instead)",
"enrichment_version": "2.1",
"sage_model": "SAGE-v1",
"sort": "priority",
"filters": {
"confirmed_only": false,
"known_exploited_only": false,
"fix_available_only": false
},
"cve_paging": {
"page": 1,
"page_size": 250,
"note": "Per-asset CVE pages; see each result's cves_page. result_hash covers all CVEs."
}
},
"_links": {
"self": "/api/v1/assets/correlate-cves"
}
}
Response fields¶
Envelope¶
| Path | Meaning |
|---|---|
api.version, api.request_id, api.timestamp, api.processing_ms | API version; unique request id (quote it to support); response time (UTC); server processing time in ms |
data.results[] | One result per submitted asset, in request order |
data.summary.total | Assets processed |
data.summary.by_status | Count per resolution.status |
data.summary.by_coverage | Count per resolution.coverage; null = not correlated |
meta.source, meta.matcher, meta.enrichment_version, meta.sage_model | Constant descriptors of the service, matcher, CVE object version and summary model |
meta.cve_paging | Page and page size in effect (present when paging is on) |
meta.sort, meta.filters | The sort mode and filters applied |
data.fix_summary[] | Top 10 fix actions across every asset in the call (see Ranking) |
meta.capec_source | CAPEC catalog and version (only with include_capec: true) |
_links.self | This endpoint |
Per asset (data.results[])¶
| Path | Meaning |
|---|---|
asset_id | Your identifier, echoed |
submitted.* | Your input fields, echoed unchanged |
resolution.status | resolved, ambiguous or unresolved (see below) |
resolution.coverage | covered, partial, no_cpe_data, or null (see below) |
resolution.confidence | 0–100 confidence in the product match |
resolution.confidence_band | HIGH (≥ 80), MEDIUM (60–79), LOW (< 60) |
resolution.vendor, resolution.product | Matched catalog vendor and product (id, name, slug); null when unresolved |
resolution.cpe | CPE vendor and product the CVE data is keyed on |
resolution.match_basis[] | Why the product matched (see below) |
candidates[] | For ambiguous only: ranked candidates (product, cpe, score, match_basis) |
cves[] | CVEs affecting this asset (one page), in the requested order (default: priority) |
cves_page | page, page_size, total (after filters), total_unfiltered, has_more |
fix_groups[] | One entry per distinct fix action for this asset, ranked (see below) |
fix_plan | For version fixes: the single upgrade that clears all known-exploited CVEs, and the one that clears every fixable CVE (see below); null when there are none |
needs_review | true when an empty or partial result must not be read as clean. An empty result is never unqualified: it carries needs_review, an ambiguous or unresolved status, or the NO_MATCHING_RANGE warning |
correlated_at | When the result was computed (UTC) |
result_hash | Hash of the resolved identity and every (CVE, tier) pair across all pages; send it to /check |
status_hash | Hash of status_facts (see Status hash); send it to /check with result_hash |
status_facts | What status_hash covers: v, known_exploited[], lifecycle, firmware_currency |
warnings[] | code and message for caveats (see below) |
Per CVE (cves[])¶
Each CVE has the fields of the CVE object, plus:
| Path | Meaning |
|---|---|
match_tier | How precisely the CVE matched the asset's version (see below) |
priority_rank | Position in the sorted, filtered list for this asset, across all pages (1 = first) |
priority_reason | Plain-language reason for the position, e.g. confirmed (affected 1.0 to 3.11), fix: upgrade beyond 3.11 (derived) |
references.vendor_advisories[] | The vendor's own advisories for this CVE: {url, title, source}. Included only when the link is on the matched vendor's own domain and NVD tagged it Vendor Advisory (source: nvd_vendor_advisory) or the vendor, as the CVE's CNA, published it (source: vendor_cna). A vendor's own domain is its name domain (e.g. moxa.com) or one of a reviewed list of other domains it publishes advisories on (e.g. android.com for Google), each approved on NVD evidence; on those, only NVD Vendor Advisory-tagged links count. A vendor advisory that CISA's CSAF document for the CVE states as its source (a self reference) is also included when it is on the vendor's own domain (source: cisa_csaf_vendor_reference, with CISA's title). Links are never constructed or guessed; title is null because NVD references carry no titles. Empty means no qualifying link, not that no advisory exists. patch.patch_url is unchanged. |
references.cve_org_url | The official CVE record at cve.org. Always present. |
references.other_references[] | Every other NVD reference for this CVE, not already in vendor_advisories, as {url, tags, provided_by} in NVD order. These are not vendor-verified: tags and provided_by (the submitter, e.g. [email protected]) are NVD's own fields. Capped at 25 per CVE. |
references.other_references_total | How many other references exist before the cap. When it is above 25, the full list is on references.nvd_url. |
references.cisa_ics_advisories[] | CISA ICS advisories that list this CVE: {advisory_id, url, title, published}. The URL is the web page each CISA CSAF document states for itself (github.com/cisagov/CSAF); none are constructed. Empty when no CISA ICS advisory lists the CVE. |
fix.available, fix.action, fix.source, fix.derived, fix.vendor_statements (only when the vendor states several versions) | The fix for this CVE on this asset: whether one is known, what to do, where it comes from (vendor, stored, derived, microsoft), and whether it was derived from the affected range |
fix.document, fix.statement, fix.contradicts_range | Present when the vendor's advisory decides the fix: the advisory ID; for a vendor "no fix", the vendor's words and, when our affected range has an end bound, that bound (version_end, version_end_inclusive, note) |
applies_to_models | Present when the product is a model family and NVD or the CVE record lists this CVE for some models only: models (catalog names, up to 10), model_count, family_model_count. Send the model for a definite answer |
affected_range.cpe_version | The specific affected version, or * for a range or product-wide row |
affected_range.is_range | true when the row is a version range |
affected_range.version_start / version_start_inclusive | Lower bound and whether it is included |
affected_range.version_end / version_end_inclusive | Upper bound and whether it is included |
capec[] | Attack patterns (only with include_capec: true) |
Frequently used CVE fields: scoring.cvss (score, vector, severity: CRITICAL ≥ 9.0, HIGH ≥ 7.0, MEDIUM ≥ 4.0, LOW), scoring.epss (probability, percentile, plain-language band), scoring.bcs (always null: BCS was retired on 2026-10-05), exploitation (kev_flagged, kev_added_at, has_public_exploit, poc_available, exploit_maturity: FUNCTIONAL → POC → WEAPONIZED → NONE), affected (vendors, protocols, device types, ICS relevance), patch (status: patched, unpatched, partial, workaround, unknown; version, URL, notes), classification.cwes, sage (plain-language summary), temporal, references. Fields with no data are null or empty lists.
Values¶
resolution.status¶
| Value | Meaning |
|---|---|
resolved | One catalog product is the clear match. Correlated when at or above min_confidence. |
ambiguous | Several products scored within 12 points of the top; see candidates[]. No CVEs. Never HIGH. |
unresolved | No product matched well enough, or the vendor is unknown. Confidence 0, no CVEs. |
resolution.coverage¶
| Value | Meaning |
|---|---|
covered | Version-bounded data exists, so a supplied version is checked |
partial | Only product-wide data exists: CVEs apply, versions cannot be checked |
no_cpe_data | No CVE data behind the product: an empty list is undetermined, not clean (needs_review) |
null | Not correlated (not resolved, or below min_confidence) |
resolution.match_basis[]¶
| Value | Meaning |
|---|---|
exact, cpe_alias, prefix, substring, token | Name match, strongest to loosest: exact name; known CPE spelling; name starts with; name contains; shared words only |
sku_map | Resolved through a curated vendor model/order-code pattern |
version:in_range, version:out_of_range | The supplied version is inside / outside the product's known ranges |
type:<part>, type_mismatch:<part> | product_type agrees / disagrees with the product's CPE part |
canonical_selected, sku_disambiguated, series_suffix, leading_token | Tie-break applied to pick one product |
match_tier (per CVE)¶
| Value | Meaning |
|---|---|
EXACT | The asset's version equals a listed affected version |
RANGE | The asset's version falls inside an affected range (see affected_range) |
PRODUCT_WIDE | The CVE applies to the product with no version bound, or no version was supplied. Not confirmed for the installed version. |
When several rows match one CVE, the most specific tier wins (EXACT > RANGE > PRODUCT_WIDE).
Warnings¶
| Code | Meaning |
|---|---|
NO_VERSION_SUPPLIED | No version; every CVE is PRODUCT_WIDE |
VERSION_NOT_USED_FOR_RESOLUTION | A version was sent but has no numeric form the resolver can use (for example R3.02.10, r130.2, B1.6.6). It was not used to identify the product and is still used for CVE matching. Before 2026-10-25 these versions were wrongly reported as NO_VERSION_SUPPLIED |
VERSION_FROM_FIRMWARE | No version; firmware_version was used for matching |
PRODUCT_WIDE_MATCH | At least one CVE applies with no version bound |
NO_CPE_DATA | No CVE data behind the resolved product; result undetermined |
PRODUCT_UNRESOLVED | The product could not be identified, so no correlation ran. Undetermined, not clean |
NO_MATCHING_RANGE | The product has affected-range data but none contains this version. Determined from structured sources only (CVE records and machine-readable vendor and government advisories); a vulnerability described only in an advisory's text would not appear |
MODEL_NOT_SPECIFIED | The product resolved to a model family (e.g. GOT2000). Some of its CVEs are listed by NVD or the CVE record for specific models only (those in the result carry applies_to_models), or CVEs are held for its models that this family-level result does not include. candidates names the models to send for a complete, model-specific result |
NEEDS_REVIEW | Below min_confidence, or no data: do not read as clean |
FIRMWARE_UNPARSEABLE | The version is not comparable; treated as absent |
VERSION_SUFFIX_APPROXIMATE | Version has letters or brackets (e.g. 1.265b, 5.0(3)); ordering approximate |
VERSION_SUFFIX_IGNORED | A space-separated suffix (e.g. SP2) was dropped |
AMBIGUOUS_RESOLUTION | Several close candidates; see candidates[] |
CANONICAL_SELECTED | Close candidates were variants of the exact-name product; that product was chosen |
VENDOR_ALIAS_APPLIED | Vendor spelling mapped to its canonical name |
VENDOR_RESOLVED_PRODUCT_NOT_FOUND | Vendor recognised, product not found |
SKU_MAP_APPLIED, SKU_MAP_DISAMBIGUATED | A curated model/order-code pattern was used |
SERIES_SUFFIX_DISAMBIGUATED | Rockwell catalog-number series suffix picked the product |
LEADING_TOKEN_RESOLVED | Resolved via the model's leading identifier |
PART_NUMBER_RESOLVED | The product text did not resolve; the submitted part_number identified the product |
BARE_NUMBER_MODEL | The model is only a short number (e.g. 860); candidates are offered, nothing is resolved |
WINDOWS_DISAMBIGUATED, OS_BUILD_RELEASE_UNCERTAIN | Windows release chosen from name/build; mapping not fully certain |
WINDOWS_RELEASE_TOKEN_NOT_COMPARED, WINDOWS_RELEASE_PARTIAL | A Windows release label could not be compared (fully or in part) against OS-build ranges |
GENERIC_FAMILY_NAME | The product is a generic family name; candidates are offered |
New codes may appear; handle unknown codes gracefully. The full list is also published in the OpenAPI spec as x-warning-codes on POST /api/v1/assets/correlate-cves.
Ranking and fix actions¶
Sort modes (options.sort)¶
| Value | Order |
|---|---|
priority (default) | 1. confirmed for this version (EXACT, RANGE) before unconfirmed (PRODUCT_WIDE); 2. known-exploited first; 3. public exploit or proof-of-concept available; 4. fix available before no fix known; 5. CVSS, then EPSS, highest first |
score | CVSS, then EPSS, highest first; ties keep match order. (Until 2026-10-05 this order started with BCS, which is retired: see the deprecation note on bcs.) |
exploit | Known-exploited, then exploit or proof-of-concept available, then EPSS, then CVSS |
newest | Published date, newest first |
Fix per CVE (fix)¶
- A fixed version the vendor's advisory states for this product:
upgrade to <version>(sourcevendor, with the advisory indocument). A version the advisory states for another product is never used. When the vendor states more than one fixed version for the product, every stated version is invendor_statementsand one is chosen: - one advisory listing a version per release line (V4.10.111, V5.0.171, ...): the smallest stated version above the device's version on the same major version. With no device version,
actionlists every line's fix (upgrade to the fixed release for your version line: ..., no single bound). - different advisories stating different versions (for example V7.2 and a later V8.0): the highest.
- when no stated version applies (the device is above every line's fix), the rules below apply.
- Otherwise a vendor statement that this product will not or cannot be fixed:
no fix; mitigation only(available: false, sourcevendor, the advisory indocument, the vendor's words instatement). It applies only when the statement names this product or a vendor series covering it (NPort 5100 Seriescovers NPort 5130) and the vendor states no fix for the product in the same CVE. When the matched range has an end bound, which would otherwise give anupgrade beyond <end>fix,contradicts_rangenames that bound. - Otherwise a fixed version stored for the CVE:
upgrade to <version>(sourcestored). - Otherwise derived from the affected range's end bound: an exclusive end means that version fixes it (
upgrade to <end> or later); an inclusive end means the end version is still affected (upgrade beyond <end>). Sourcederived,derived: true. - Otherwise a stored "patched" status without a version:
vendor fix available (version not recorded). - Otherwise
no fix known(exact-version and product-wide matches carry no bound to derive from).
Derived fixes come from the affected version ranges, not from a vendor fix statement. Confirm the target release in the vendor's advisory: that release may not exist in the product line.
fix_groups[]¶
One group per distinct fix action, over the filtered CVEs of all pages, with no fix known last. Groups are ranked by their highest-priority CVE (same rules as priority), then by known-exploited, exploit and total counts.
| Field | Meaning |
|---|---|
fix | The action, e.g. upgrade beyond 3.11 |
fix_type | version, vendor, kb, esu or none |
source, derived | Where the action comes from; derived: true when taken from an affected range |
cve_ids[] | CVEs this action clears, in priority order |
counts | total, confirmed, known_exploited, exploit_available |
highest_score | Highest cvss in the group; bcs is deprecated (legacy stored value, no longer used for ranking) |
group_rank | 1 = do first |
fix_plan¶
Each CVE's range usually ends at a different patch release, so a device can have many version groups. fix_plan answers the practical question in two lines:
| Field | Meaning |
|---|---|
to_clear_known_exploited | The one upgrade that moves past every known-exploited CVE's affected range, with what it clears (cves, known_exploited, groups) |
to_clear_all_fixable | The one upgrade that moves past every version-fixable CVE's range |
derived, source, note | Derived plans always carry the note: derived from affected version ranges; confirm the target release in the vendor's advisory, as it may not exist in this product line |
target | The version behind fix: version, and still_affected (true when that version is itself affected, as in "upgrade beyond 11.004"; false when it fixes the CVEs, as in "upgrade to 2.7 or later") |
The plan assumes one release line. null when the asset has no version fixes.
Devices without a version. Most inventories list devices without one. Send vendor and product only: every known CVE for the product comes back as product-level (NO_VERSION_SUPPLIED), each with its fix, and fix_plan gives the one upgrade that clears every CVE with a version fix. Where firmware currency covers the product, the latest listed release is shown too (see Lifecycle and Firmware Currency).
data.fix_summary[]¶
The same fix action on the same product, aggregated across every asset in the call; the top 10, excluding no fix known. Each entry: rank, fix, product, fix_type, source, derived, asset_ids, counts (assets, cves, known_exploited, exploit_available, confirmed) and highest_score.
Example: a device with Known-Exploited CVEs (FortiOS 7.0.0, real response, abridged)¶
{
"asset_id": "EXAMPLE-FW-01",
"cves (first 2 of 163, fields abridged)": [
{
"cve_id": "CVE-2022-40684",
"match_tier": "RANGE",
"priority_rank": 1,
"priority_reason": "confirmed (affected 7.0.0 to 7.0.7), known-exploited, public exploit available, fix: upgrade to 7.0.7 or later (derived)",
"fix": {
"available": true,
"action": "upgrade to 7.0.7 or later",
"source": "derived",
"derived": true
}
},
{
"cve_id": "CVE-2022-42475",
"match_tier": "RANGE",
"priority_rank": 2,
"priority_reason": "confirmed (affected 7.0.0 to 7.0.8), known-exploited, proof-of-concept available, fix: upgrade beyond 7.0.8 (derived)",
"fix": {
"available": true,
"action": "upgrade beyond 7.0.8",
"source": "derived",
"derived": true
}
}
],
"fix_groups (first 2 of 40)": [
{
"fix": "upgrade to 7.0.7 or later",
"fix_type": "version",
"source": "derived",
"derived": true,
"cve_ids": [
"CVE-2022-40684",
"CVE-2022-29055"
],
"counts": {
"total": 2,
"confirmed": 2,
"known_exploited": 1,
"exploit_available": 1
},
"highest_score": {
"bcs": 10.0,
"cvss": 9.8
},
"group_rank": 1
},
{
"fix": "upgrade beyond 7.0.8",
"fix_type": "version",
"source": "derived",
"derived": true,
"cve_ids": [
"CVE-2022-42475",
"CVE-2022-41335",
"CVE-2022-42476",
"CVE-2022-42472",
"\u2026"
],
"counts": {
"total": 5,
"confirmed": 5,
"known_exploited": 1,
"exploit_available": 1
},
"highest_score": {
"bcs": 10.0,
"cvss": 9.8
},
"group_rank": 2
}
],
"fix_plan": {
"to_clear_known_exploited": {
"fix": "upgrade beyond 7.0.19",
"derived": true,
"source": "derived",
"clears": {
"cves": 137,
"known_exploited": 12,
"groups": 31
},
"note": "Derived from affected version ranges, not from a vendor fix statement. Confirm the target release in the vendor's advisory: that release may not exist in this product line."
},
"to_clear_all_fixable": {
"fix": "upgrade beyond 7.6.6",
"derived": true,
"source": "derived",
"clears": {
"cves": 150,
"known_exploited": 12,
"groups": 38
},
"note": "Derived from affected version ranges, not from a vendor fix statement. Confirm the target release in the vendor's advisory: that release may not exist in this product line."
}
}
}
Paging¶
Each asset's CVE list is paged (API keys: 250 per page by default). If any result has cves_page.has_more: true, repeat the call with options.cve_page + 1. result_hash, cves_page.total and PRODUCT_WIDE_MATCH always describe the full list, so a hash does not change between pages.
Staleness check¶
Re-running a full correlation to find out whether anything changed is expensive. Send the result_hash you stored instead; only assets with changed: true need a fresh correlate-cves call. The check still resolves and matches each distinct device again (about 0.2 s each): 200 distinct devices take about 40 seconds, so use a client timeout of at least 90 seconds, and after a timeout send batches of at most 50.
curl -X POST https://breachspider.com/api/v1/assets/correlate-cves/check \
-H "Authorization: Bearer bs_live_..." \
-H "Content-Type: application/json" \
-d '{
"assets": [
{"asset_id": "EXAMPLE-SWITCH-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5",
"result_hash": "sha256:ee5e58d4b621d3ce37f9f3df9b924b0cfa7006e2323daefd1d6f2b84c561756a"}
]
}'
The response lists, per asset, changed (true/false), current_hash and a reason, plus data.changed[] with the asset ids that changed.
If the earlier correlate-cves call set options.min_confidence, send the same value here ("options": {"min_confidence": "HIGH"}; default MEDIUM, as on correlate-cves). The hash is recomputed under that gate, so a result is always compared like for like.
Status hash¶
result_hash changes only when the findings change: what the device resolves to, which CVEs match, their match tier, or the advisory evidence behind them. Other things about a device can change while its findings stay the same. status_hash covers them: SHA-256 over sorted-key compact JSON of status_facts, so you can recompute it yourself.
status_facts field | Contents |
|---|---|
v | Format version, 1 |
known_exploited[] | The matched CVEs on the known-exploited list, sorted (every page, before filters) |
lifecycle | support_status; end_of_support (answer, date, reason); dates (end_of_sale, end_of_support, end_of_life, security_support_end, each status and date); editions where listed. null when no lifecycle answer is given |
firmware_currency | status, reason, latest_version, releases_behind. null when no firmware answer is given |
No URL, quote, text or as_of date is included. The lifecycle and firmware_currency answers are given to client plans only, so the same device can have a different status_hash for a different caller; compare hashes from the same key.
To check both, send status_hash with result_hash, and the saved status_facts to learn what changed:
{"assets": [{"asset_id": "EXAMPLE-SWITCH-01", "vendor": "Moxa", "product": "EDS-518A", "version": "V3.5",
"result_hash": "sha256:ee5e...", "status_hash": "sha256:41c0...", "status_facts": {"v": 1, "...": "..."}}]}
Each asset sent with status_hash also gets:
| Field | Meaning |
|---|---|
findings_changed | Same as changed: result_hash differs |
status_changed | status_hash differs |
current_status_hash, current_status_facts | The current values; store them for the next check |
reasons[] | code and text per change, plus cve_ids or from and to where useful |
data.status_changed[] lists the assets whose status changed. Assets sent without status_hash get exactly the earlier response.
Sent status_facts must have exactly the four fields above (v = 1, known_exploited a list of at most 4,000 CVE ids) and be at most 64 KB; otherwise the call answers 422 VALIDATION_ERROR. They are used to name changes only when they hash to the status_hash sent with them. Edited or damaged facts are ignored: the change is then reported from the hashes alone, with the reason STATUS_CHANGED ("status changed"). Sent facts are never returned.
| Reason code | When |
|---|---|
FINDINGS_CHANGED | result_hash differs; run correlate-cves again for the new and resolved findings |
NEWLY_KNOWN_EXPLOITED, NO_LONGER_KNOWN_EXPLOITED | A matched CVE was added to or removed from the known-exploited list (cve_ids) |
SUPPORT_STATUS_CHANGED | lifecycle.support_status changed (from, to) |
END_OF_SALE_DATE_PUBLISHED, END_OF_SUPPORT_DATE_PUBLISHED, END_OF_LIFE_DATE_PUBLISHED, SECURITY_SUPPORT_END_DATE_PUBLISHED | A date is now stated; also ..._CHANGED and ..._REMOVED |
LIFECYCLE_PUBLISHED, LIFECYCLE_REMOVED, LIFECYCLE_CHANGED | A lifecycle answer is now given, no longer given, or changed in another way. When the vendor data behind an answer is gone, the answer is still given, as unknown, and SUPPORT_STATUS_CHANGED names the change |
NEW_FIRMWARE_RELEASE | The latest listed firmware release changed to another listed release (from, to). Not given when no release is listed any more; FIRMWARE_STATUS_CHANGED names that change |
RELEASES_BEHIND_CHANGED, FIRMWARE_STATUS_CHANGED | Releases behind or the currency status changed |
FIRMWARE_PUBLISHED, FIRMWARE_REMOVED, FIRMWARE_CHANGED | A firmware answer is now given, no longer given, or changed in another way |
STATUS_CHANGED | The status changed, but no matching status_facts was sent, so the change cannot be named |
What changes each hash¶
| Change | result_hash | status_hash |
|---|---|---|
| A CVE newly matches, or no longer matches | changes | changes only if that CVE is known-exploited |
A CVE moves between EXACT, RANGE and PRODUCT_WIDE | changes | same |
| A vendor fix, workaround or mitigation is published or edited | changes | same |
| The advisory behind a version range changes | changes | same |
| Only an advisory or source URL changes | same | same |
| A different product, CPE or version | changes | changes if its facts differ |
| CVSS, EPSS, patch status or patch version | same | same |
| A matched CVE is added to or removed from the known-exploited list | same | changes |
| A lifecycle status or date | same | changes |
| A new firmware release, or releases behind | same | changes |
Errors¶
| HTTP | Code | When |
|---|---|---|
| 401 | AUTH_REQUIRED | Missing, invalid, expired or revoked key |
| 413 | BATCH_TOO_LARGE (error.detail.error is batch_too_large) | More than 200 assets; error.max and error.detail.max give the limit |
| 422 | VALIDATION_ERROR | Missing asset_id, vendor or product; asset_id longer than 64 characters or an IP, MAC, hostname or email (type forbidden_value); invalid min_confidence, cve_page, cve_page_size or sort (message: "sort must be one of: priority, score, exploit, newest") |
| 429 | RATE_LIMITED (error.detail.retry_after = seconds to wait) | Per-key request or asset limit exceeded |
| 400 | UNKNOWN_PARAMETER | Query parameters are not accepted on these calls |
Every error also carries retryable, retry_after_seconds and action (and max on the 413); never retry when retryable is false. See Retry guidance.
Changes¶
- 2026-11-13 (source precedence): all additive.
- A vendor's own advisory or CSAF range, fix version or "all versions, no fix" statement for the product decides over a product-wide record or a wider NVD range:
CONFIRMED_AFFECTED(vendor) when the version is inside it,LIKELY_NOT_AFFECTEDwhen it is outside. Each CVE where a record was overridden carriessource_conflicts(rule,kept,overridden,outcome), and the device gets the warningSOURCE_CONFLICT_RESOLVED.result_hashis unchanged (match tiers do not change). - TIA Portal device labels ("PLC_1 [CPU 1516F-3 PN/DP]") resolve as the text in brackets (warning
TIA_DEVICE_LABEL); TIA Portal naming variants of S7 CPUs and STEP 7 resolve through catalog aliases. known_productmay carryrelated_advisorieswhen an advisory names a component of the product (for example its HART DTM) rather than the device firmware.- 2026-11-12 (catalog-wide review): all additive.
- Rockwell Stratix switches are checked as the Rockwell product and as the Cisco IOS XE they run (warning
ALSO_CHECKED_AS). - A version only NVD's wider range holds, where the vendor's own statement or the CVE record excludes it, is now
POSSIBLY_AFFECTED("NVD lists this version; ..."), neverCONFIRMED_AFFECTED. - Names written as advisories write them ("SCALANCE W734-1 RJ45 (6GK5734-1FX00-0AA0)") resolve through the order number or the model inside the name (warning
MODEL_FOUND_IN_NAME). When the text names more than the product found, the result saysFAMILY_ONLY_MATCHandneeds_reviewis true. - A version that names a firmware program ("ASCD2 v2.04.0.0") is compared only with ranges for the same program (warning
VERSION_PROGRAM_CODE,needs_reviewtrue). - An unresolved device that a vendor's own product or lifecycle list names gets a new object
known_product(model,part_number,vendor,source.title,source.url,source.listed_on,as_of,statement) and the warningKNOWN_PRODUCT_NO_CVES_IN_SOURCES.resolution.statusstaysunresolvedandneeds_reviewstays true: no CVE in our sources is not a statement that the device has no vulnerabilities. - More version ranges are read from CSAF advisories. Devices whose findings change through these fixes read as changed once on
/correlate-cves/check. - 2026-11-12:
/correlate-cves/checkcomputes each distinct device once per call and runs devices in parallel (68 devices took about 29 s, so clients with a 30 s timeout failed; now about 14 s). Documented the time per call and the 90 s client timeout. Results and hashes are unchanged. - 2026-10-27: new fields
status_hashandstatus_factsper result (Status hash)./correlate-cves/checkacceptsstatus_hashandstatus_factsper asset andoptions.min_confidence(defaultMEDIUM); before, the check always recomputed atMEDIUM, so results made atLOWorHIGHcould read as changed.result_hashis unchanged: saved hashes keep working. - 2026-10-24: new optional
assets[].part_number(also on/assets/correlate-cves/check), echoed insubmitted. Matched exactly, numeric order codes included, against vendor part numbers for thelifecycleandfirmware_currencyblocks (matched_catalog_item.match_method: submitted_part_number); used to identify the product only when the product text does not resolve (warningPART_NUMBER_RESOLVED). Devices sent without it are matched exactly as before;result_hashis unchanged for them. - 2026-10-10:
meta.matchernow readsstateless; same version-range rules as stored matching, without the stored product-level and vendor-only fallbacks (reported as coverage and warnings instead). Stored matching (assets uploaded to an environment) also adds a product-level match for a product that has no version ranges (MEDIUM) and a vendor-only match when no product is linked (LOW; skipped for vendors with over 1,000 CVEs). A stateless call returns those cases ascoverage: no_cpe_datawith a warning, not as matches. - 2026-09-26 (late):
meta.matchernow readsstateless; same rules as stored matching(it previously named an internal database view). Informational only; do not parse it. - 2026-09-26 (evening): every response is ranked by what's exposed and what to fix first.
cves[]defaults topriorityorder (options.sort:priority,score= previous order,exploit,newest); new optional filtersconfirmed_only,known_exploited_only,fix_available_only; new fieldspriority_rank,priority_reasonandfixper CVE,fix_groupsandfix_planper asset,data.fix_summaryper call,cves_page.total_unfiltered,meta.sort,meta.filters.result_hashis unchanged and independent of sort, filters and page. - 2026-09-26:
firmware_versionis used for matching whenversionis empty (VERSION_FROM_FIRMWARE); per-asset CVE paging (cve_page,cve_page_size,cves_page); for API keysinclude_capecnow defaults tofalseandcve_page_sizeto 250; per-key rate limits; expired and revoked keys rejected; CVE fieldstemporal.modified_at,temporal.enriched_at,exploitation.kev_added_at,temporal.kev_added_at,patch.patch_url,affected.ics_relevance_scoreandaffected.device_typesare now populated.