elastic / elastic/integrations
[xm_cyber] Migrate VRM data streams to new v2 vrmReport API
- Dominant language
- Handlebars
- Stars
- 333
- Forks
- 647
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 225
Description
**Integration Name:** XM Cyber (`xm_cyber`)
**Dataset Name:** `vulnerability`, `device`, `product` (plus a proposed new `vulnerability_instances`)
**Integration Version:** 0.4.0
### Goal
XM Cyber has advised that the VRM public API endpoints the integration currently uses are deprecated and should be migrated to the new v2 `vrmReport` endpoints.
### Existing Features
The `vulnerability`, `device`, and `product` data streams currently poll the deprecated endpoints:
- `GET /api/v2/vrm/public/vulnerabilities`
- `GET /api/v2/vrm/public/devices`
- `GET /api/v2/vrm/public/products`
### Requested change
Migrate each to its `vrmReport` equivalent:
- `GET /api/v2/vrm/public/vrmReport/vulnerabilities`
- `GET /api/v2/vrm/public/vrmReport/devices`
- `GET /api/v2/vrm/public/vrmReport/products`
This is a breaking change and requires more than a path swap:
- **Pagination:** the CEL programs currently follow `body.meta.next`. The new responses paginate via a top-level `nextPageLink` field, alongside new top-level `total` and `lastDataUpdate` fields. The `want_more`/`next_page.link` logic in each `cel.yml.hbs` needs updating.
- **Response schemas:** field sets have changed and expanded (e.g. EPSS scores, CVSS v4, choke-point metrics, critical-asset counts, and per-source enrichment URLs). Ingest pipelines, field mappings, sample/test events, and dashboards will need to be updated accordingly.
- **New data stream:** the new API adds a `vulnerabilityInstances` endpoint (`GET /api/v2/vrm/public/vrmReport/vulnerabilityInstances`) that correlates each device with installed product versions and the specific CVEs affecting them. We should add this as a new `vulnerability_instances` data stream.
### Note on introducing the breaking change
The integration is still in **technical preview** (currently v0.4.0, pre-1.0.0), so we can introduce this breaking change through a normal integration update without the usual GA breaking-change constraints. This is also time-sensitive: **XM Cyber is fully deprecating the current API**, so any user of these data streams will break once the old endpoints are removed unless the integration is migrated to the new `vrmReport` API. We should prioritise this ahead of that deprecation.
### Anything else?
Full field-level schemas for the new endpoints are available in XM Cyber's "VRM reports public API" documentation (internal). Can share the relevant schema details with whoever picks this up.
Contributor guide
Assessment
This issue has not been assessed yet.