From 40881f3d474972242152f0a5b1756e517764df04 Mon Sep 17 00:00:00 2001
From: Bryce <blewis@cycle.io>
Date: Tue, 21 Jul 2026 10:39:17 -0700
Subject: [PATCH]  add network neighbors to server telemetry

---
 .../network/ServerTelemetryNetwork.yml        | 10 ++++++
 .../ServerTelemetryNetworkNeighbor.yml        | 34 +++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetworkNeighbor.yml

diff --git a/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetwork.yml b/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetwork.yml
index a85e2f39..e91319f9 100644
--- a/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetwork.yml
+++ b/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetwork.yml
@@ -3,6 +3,7 @@ title: ServerTelemetryNetwork
 description: Network telemetry for the server.
 required:
   - devices
+  - neighbors
 properties:
   devices:
     type:
@@ -11,3 +12,12 @@ properties:
     description: Per-interface network counters, keyed by interface name.
     additionalProperties:
       $ref: ./ServerTelemetryDeviceStats.yml
+  neighbors:
+    type:
+      - array
+      - "null"
+    description: >-
+      Live network neighbors (ARP/NDP table entries) discovered via the
+      kernel netlink API, covering both IPv4 (ARP) and IPv6 (NDP).
+    items:
+      $ref: ./ServerTelemetryNetworkNeighbor.yml
diff --git a/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetworkNeighbor.yml b/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetworkNeighbor.yml
new file mode 100644
index 00000000..c4f4d9dd
--- /dev/null
+++ b/components/schemas/infrastructure/servers/telemetry/snapshot/network/ServerTelemetryNetworkNeighbor.yml
@@ -0,0 +1,34 @@
+type: object
+title: ServerTelemetryNetworkNeighbor
+description: A single entry in the server's ARP/NDP neighbor table.
+required:
+  - ip
+  - device
+  - state
+properties:
+  ip:
+    type: string
+    description: The IP address of the neighbor (IPv4 or IPv6).
+  device:
+    type: string
+    description: The network interface the neighbor was discovered on.
+  mac:
+    type: string
+    description: >-
+      The MAC address of the neighbor. Omitted for incomplete or failed
+      entries, matching `ip neigh` behavior.
+  state:
+    type: string
+    description: >-
+      The NUD (Neighbor Unreachability Detection) state of the entry.
+    enum:
+      - INCOMPLETE
+      - REACHABLE
+      - STALE
+      - DELAY
+      - PROBE
+      - FAILED
+      - NOARP
+      - PERMANENT
+      - NONE
+      - UNKNOWN