Heartbeat & Configuration
Heartbeat
The sensor periodically samples host metrics (internal/heartbeat) using gopsutil and POSTs them to POST /api/sensors/{id}/agent/heartbeat. The Defense Center uses these to track sensor health and online/offline status.
Sampled fields:
| Field (JSON) | Source |
|---|---|
cpuUsage | cpu.Percent (overall) |
memoryUsed / memoryTotal / memoryPercent | mem.VirtualMemory |
| per-interface counters | network interface sampling |
Heartbeats are resilient: a failed POST is logged and retried on the next tick — it never crashes the agent.
The backend treats a sensor as offline when heartbeats stop for
SensorSettings__HeartbeatTimeoutMinutes(see Deployment configuration).
Configuration
Configuration comes from environment variables and flags. Persisted credential files win over environment variables.
| Variable | Default | Description |
|---|---|---|
SENSOR_ID | set by enroll | Unique sensor identifier |
BACKEND_URL | required before enroll | Defense Center API base URL |
SENSOR_TOKEN | none | Durable post-enroll token; file wins over env |
HEARTBEAT_INTERVAL | 30 | Seconds between heartbeats |
SENSOR_PORT | 22 | SSH port reported during enrollment |
SUDO_USER | sensoradmin | Privileged username reported |
SENSOR_API_HOST | localhost | Data-collector gRPC host (daemon mode) |
SENSOR_API_PORT | 50051 | Data-collector gRPC port (daemon mode) |
SURICATA_SOCKET | /var/run/suricata/suricata.sock | Suricata eve.json unix socket path |
FLUSH_INTERVAL_MS | 1000 | Queue flush/drain interval (ms) |
RAVENXCOPE_LAUNCHER | auto | Force launcher: docker or systemd |
mTLS material (cert/key/root-CA paths) and the NATS URL/creds are configured alongside these and are populated during enrollment.