Events format

The incoming events from the agents must be parseable by the flatbuffer schemas, otherwise it will trigger an exception, and the event won't reach the vulnerability scanner. Below, we detail the format for the different systems supported by the scanner.

InventorySync flow and detection batches

InventorySync normalizes input into a batch flow that drives vulnerability detection:

InventorySync -> ScanContext -> Orchestrator -> Indexer + Engine

Each batch contains a Start event plus a set of DataValue and DataContext items.

On the agent side, Syscollector gathers the inventory (OS, packages, hotfixes) and sends it to the manager. InventorySync runs on the manager, normalizes the input into Start/DataValue/DataContext batches, and the vulnerability scanner consumes those batches (it does not process Syscollector payloads directly).

Batch elements

• Start: Defines the scan boundary. The start index is derived from the DataValue items present in the batch.
• DataValue: Delta items with an operation (upsert or delete) and version.
• DataContext: Same schema as DataValue, but without operation or version. It provides the extra context needed to evaluate deltas.

The id field in DataValue/DataContext is the inventory item identifier. VD uses it as the package detection base, and as the OS item_id for delete tracking.

InventorySync indices used by VD

• wazuh-states-inventory-system (OS)
• wazuh-states-inventory-packages (packages)
• wazuh-states-inventory-hotfixes (hotfixes, Windows)

Scenarios

• VDFirst: All inventory is carried in DataValue items (OS/packages/hotfix upserts).
• VDSync FullScanWithDiff: DataValue includes OS upserts and deletes plus package upserts and deletes. DataContext carries the full package inventory.
• VDSync package delta: DataValue includes package upserts and deletes. DataContext includes OS.

Inventory document payloads

DataValue and DataContext carry JSON inventory documents. VD expects the InventorySync schema and only reads the fields listed below.

• OS documents (System index) use the host object:

{
  "host": {
    "hostname": "host1",
    "architecture": "x86_64",
    "os": {
      "name": "Ubuntu",
      "platform": "ubuntu",
      "type": "linux",
      "version": "24.04.2 LTS (Noble Numbat)",
      "full": "Ubuntu 24.04.2 LTS (Noble Numbat)",
      "codename": "noble",
      "major": "24",
      "minor": "04",
      "patch": "2",
      "build": "0",
      "distribution": { "release": "6.8.0-71-generic" },
      "kernel": { "release": "6.8.0-71-generic", "version": "#71-Ubuntu SMP ..." }
    }
  }
}

• Package documents (Packages index) use the package object:

{
  "package": {
    "name": "openssl",
    "version": "3.0.2",
    "type": "deb",
    "architecture": "amd64",
    "vendor": "Ubuntu",
    "description": "Secure Sockets and Transport Layer Security",
    "installed": "2024-10-01T10:00:00Z",
    "size": 123456,
    "source": "openssl",
    "path": "/usr/bin/openssl",
    "priority": "optional",
    "multiarch": "same",
    "category": "libs"
  }
}

• Hotfix documents (Hotfixes index) use the package.hotfix object:

{
  "package": {
    "hotfix": { "name": "KB5034763" }
  }
}

ScanContext normalization

• agent.host.os always reflects the current OS from Start.
• host.os always reflects the current OS, enriched with extended fields from the OS DataValue/DataContext.
• host.os.full is built from OS name and version (macOS uses codename), and host.os.version is built from major.minor.patch.build.
• package represents the affected component. For OS detections, package.* is populated with OS data (or osDeleted when deleting).
• osDeleted carries the minimal OS data required to mark CVEs as solved.
• OS scan is supported only for Windows and Darwin. Linux OS scan is not supported (the kernel is treated as a package).
• Hotfix context tracks currently installed hotfixes; delete operations are ignored.

Indexer and engine interactions

• EventGetContext returns only _id and vulnerability.id. When needed, packages are fetched in batches by detectionId.
• EventGetCve uses deletes to mark package vulnerabilities as solved.
• Detection IDs are built as:
  • Packages: <agentId>_<packageInventoryId>_<cveId>
  • OS: <agentId>_<osName>_<osVersion>_<cveId>
• Engine events are sent with POST /events/enriched to the queue-http.sock socket using Content-Type: application/x-wev1, protocol H/E, and queue id v (QUEUE_ID).

Engine event payload example

The engine payload is a multi-line H/E message. The header (H) contains agent/host metadata, followed by one E line per event:

H	{"agent":{"id":"001","name":"agent1"},"host":{"hostname":"host1","architecture":"x86_64","os":{"name":"Ubuntu","version":"24.04.2","platform":"ubuntu","type":"linux"}}}
E	v:vulnerability-scanner:{"collector":"packages","module":"vulnerability-scanner","data":{"event":{"created":"2025-05-05T19:04:19.577Z","type":"upsert"},"host":{"os":{"full":"Ubuntu 24.04.2 LTS (Noble Numbat)","name":"Ubuntu","platform":"ubuntu","type":"linux","version":"24.04.2"}},"package":{"name":"openssl","type":"deb","version":"3.0.2"},"vulnerability":{"id":"CVE-2016-2781","severity":"Medium"}}}
E	v:vulnerability-scanner:{"collector":"system","module":"vulnerability-scanner","data":{"event":{"created":"2025-05-05T19:23:53.627Z","type":"delete"},"host":{"os":{"full":"Microsoft Windows Server 2019 Datacenter Evaluation 10.0.17763.1935","name":"Microsoft Windows Server 2019 Datacenter Evaluation","platform":"windows","type":"windows","version":"10.0.17763.1935"}},"package":{"name":"Microsoft Windows Server 2019 Datacenter Evaluation 10.0.17763.1935","type":"windows","version":"10.0.17763.1935"},"vulnerability":{"id":"CVE-2024-43558","severity":"Medium"}}}

Legacy Syscollector event types (agent-side reference)

Raw Syscollector payloads are documented in docs/ref/modules/syscollector/events.md. InventorySync normalizes them and sends Start/DataValue/DataContext batches to the manager, which are the only inputs VD consumes.