Skip to content

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)

  1. A fixed version the vendor's advisory states for this product: upgrade to <version> (source vendor, with the advisory in document). 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 in vendor_statements and one is chosen:
  2. 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, action lists every line's fix (upgrade to the fixed release for your version line: ..., no single bound).
  3. different advisories stating different versions (for example V7.2 and a later V8.0): the highest.
  4. when no stated version applies (the device is above every line's fix), the rules below apply.
  5. Otherwise a vendor statement that this product will not or cannot be fixed: no fix; mitigation only (available: false, source vendor, the advisory in document, the vendor's words in statement). It applies only when the statement names this product or a vendor series covering it (NPort 5100 Series covers 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 an upgrade beyond <end> fix, contradicts_range names that bound.
  6. Otherwise a fixed version stored for the CVE: upgrade to <version> (source stored).
  7. 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>). Source derived, derived: true.
  8. Otherwise a stored "patched" status without a version: vendor fix available (version not recorded).
  9. 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_AFFECTED when it is outside. Each CVE where a record was overridden carries source_conflicts (rule, kept, overridden, outcome), and the device gets the warning SOURCE_CONFLICT_RESOLVED. result_hash is 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_product may carry related_advisories when 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; ..."), never CONFIRMED_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 says FAMILY_ONLY_MATCH and needs_review is 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_review true).
  • 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 warning KNOWN_PRODUCT_NO_CVES_IN_SOURCES. resolution.status stays unresolved and needs_review stays 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/check computes 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_hash and status_facts per result (Status hash). /correlate-cves/check accepts status_hash and status_facts per asset and options.min_confidence (default MEDIUM); before, the check always recomputed at MEDIUM, so results made at LOW or HIGH could read as changed. result_hash is unchanged: saved hashes keep working.
  • 2026-10-24: new optional assets[].part_number (also on /assets/correlate-cves/check), echoed in submitted. Matched exactly, numeric order codes included, against vendor part numbers for the lifecycle and firmware_currency blocks (matched_catalog_item.match_method: submitted_part_number); used to identify the product only when the product text does not resolve (warning PART_NUMBER_RESOLVED). Devices sent without it are matched exactly as before; result_hash is unchanged for them.
  • 2026-10-10: meta.matcher now reads stateless; 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 as coverage: no_cpe_data with a warning, not as matches.
  • 2026-09-26 (late): meta.matcher now reads stateless; 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 to priority order (options.sort: priority, score = previous order, exploit, newest); new optional filters confirmed_only, known_exploited_only, fix_available_only; new fields priority_rank, priority_reason and fix per CVE, fix_groups and fix_plan per asset, data.fix_summary per call, cves_page.total_unfiltered, meta.sort, meta.filters. result_hash is unchanged and independent of sort, filters and page.
  • 2026-09-26: firmware_version is used for matching when version is empty (VERSION_FROM_FIRMWARE); per-asset CVE paging (cve_page, cve_page_size, cves_page); for API keys include_capec now defaults to false and cve_page_size to 250; per-key rate limits; expired and revoked keys rejected; CVE fields temporal.modified_at, temporal.enriched_at, exploitation.kev_added_at, temporal.kev_added_at, patch.patch_url, affected.ics_relevance_score and affected.device_types are now populated.