Skip to content

Payload and ingest

Ingest kind

Section titled “Ingest kind”

host_inventory — handled by the Ingestor service’s POST /v1/ingest (internal/domain/ingest, AllowedKinds, dispatched to internal/domain/hostinventory). Cloud Backend has no ingest endpoint of any kind — it owns host_agents lifecycle only (enroll/approve/reject/revoke/token-refresh). It’s a normal ALLOWED_INGEST_KINDS entry on the Edge side too, flowing through the same push_ingest/ingest_queue path as every other kind — no special-casing needed there.

Auth

Section titled “Auth”
PathAuth headerhost_agent resolved from
Via EdgeX-Device-Key (Edge’s own device key) to Ingestor; host used X-Host-Token to the gateway, checked against a Cloud-synced hash cache(tenant_id, host_id) — host_id is in the payload, since Edge presents on behalf of many hosts
Direct to IngestorAuthorization: Bearer <host_token>The token itself

Ingestor’s middleware.HostTokenOrDeviceKey accepts either on the same route.

Payload shape

Section titled “Payload shape”
{
  "host_id": "uuid",
  "agent_version": "0.1.0",
  "collected_at": "2026-07-16T10:00:00Z",
  "os": { "family": "linux", "name": "Ubuntu 24.04", "version": "...", "architecture": "x86_64" },
  "hardware": { "manufacturer": null, "cpu_cores": 8, "ram_total_bytes": 17179869184 },
  "network_interfaces": [{ "name": "eth0", "mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.0.0.5" }],
  "installed_software": [{ "name": "OpenSSL", "version": "3.0.13" }],
  "elevated_data": { "collected": false }
}

hardware.manufacturer/model/serial_number are always null in this MVP — reliable cross-platform detection needs vendor-specific sources (Linux DMI, Windows WMI) not yet implemented. elevated_data is always {collected: false, ...null} — a payload skeleton only, no real BitLocker/LUKS/users/patches probing yet.

Full schema in hostzu/spec.md and hostzu-common::inventory::HostInventoryPayload.

Storage

Section titled “Storage”

Raw payload → Azure Blob Storage (hostinventory.BlobStore, in the Ingestor repo — HOST_AGENT_BLOB_LOCAL_ROOT local-disk fallback for dev). A trimmed summary (os/hardware/network, not the full software list) lives in host_inventory_snapshots (one row per host, upserted) for fast UI reads; the full envelope is also appended to host_ingest_events as an audit log. Both tables are schema’d by Backend’s migrations (V52/V53) but written by Ingestor, not Backend.

Cadence

Section titled “Cadence”
  • Full snapshot every 12h (policy per site — site_device_policies.snapshot_interval_hours).
  • Push-on-change (software/IP/hostname/reboot diff detection) is spec’d but not implemented — every send today is a fresh full snapshot on the fixed interval only.
Section titled “Related”