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).

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.

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

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
        },
        "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": {
                "score": 6.84,
                "tier": "MEDIUM",
                "factors": {
                  "kev_flagged": false,
                  "poc_available": false,
                  "has_public_exploit": false,
                  "patch_available": false,
                  "ics_relevance": 0.7
                }
              }
            },
            "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": {
                "score": 5.57,
                "tier": "MEDIUM",
                "factors": {
                  "kev_flagged": false,
                  "poc_available": false,
                  "has_public_exploit": false,
                  "patch_available": false,
                  "ics_relevance": 0.15
                }
              }
            },
            "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 rules as stored matching",
    "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

Per asset (data.results[])

Per CVE (cves[])

Each CVE has the fields of the CVE object, plus:

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 (BreachSpider Composite Score 0–10 and tier, same bands as CVSS, with its inputs), 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

resolution.coverage

resolution.match_basis[]

match_tier (per CVE)

When several rows match one CVE, the most specific tier wins (EXACT > RANGE > PRODUCT_WIDE).

Warnings

New codes may appear; handle unknown codes gracefully.

Ranking and fix actions

Sort modes (options.sort)

Fix per CVE (fix)

1. A fixed version stored for the CVE: upgrade to <version> (source stored).
2. 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.
3. Otherwise a stored "patched" status without a version: vendor fix available (version not recorded).
4. 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.

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:

The plan assumes one release line. null when the asset has no version fixes.

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.

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.

Errors

Changes

• 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.