Skip to main content

Overview

Introduction​

The Ravenxcope Sensor Agent is a lightweight Go service that runs on each physical sensor host. It is the only software component that executes directly on sensor machines — all other RavenXcope services run on the defense center infrastructure.

The agent has two core responsibilities:

  1. Enrollment — On first startup, register the sensor host with the backend using a one-time install token, reporting hostname, OS, architecture, network interfaces, and IP address.
  2. Heartbeat — Periodically send system metrics (CPU, memory, network interface counters) to the backend so the defense center can monitor sensor health and online status.

Role in the Architecture​

Defense CenterBackend APIDashboard / AnsibleSensor HostSensor AgentGo / Metrics / SuricataHTTPS / JSON

The agent communicates exclusively with the backend API over HTTP. It does not interact with the frontend, Ansible service, or any database directly.

Technology Stack​

CategoryTechnologyVersionPurpose
LanguageGo1.22Agent runtime
System Metricsgopsutilv3.24.5CPU, memory, and network I/O collection
Container BaseAlpine LinuxlatestMinimal Docker runtime
BuildMulti-stage Docker—Static Go binary in Alpine

Agent Version​

The current agent version is 2.0.0, defined as a constant in main.go. This version is reported to the backend during enrollment to track agent compatibility across the sensor fleet.

Key Design Principles​

  1. Single binary — The entire agent is a single Go binary (main.go) with no external dependencies beyond the OS.

  2. Fail-fast on configuration — The agent exits immediately if required environment variables (SENSOR_ID, BACKEND_URL) are missing.

  3. Enrollment-once model — The agent enrolls once using a one-time INSTALL_TOKEN, receives a durable SENSOR_TOKEN, and persists it to disk. Subsequent restarts skip enrollment.

  4. Host network mode — The agent runs with Docker --network host to accurately detect and report host network interfaces and metrics.

  5. Host metadata passthrough — OS info and hostname are read from bind-mounted host files (/host-os-release, /host-hostname) rather than container metadata.

  6. Resilient heartbeat loop — Failed heartbeats are logged but do not crash the agent. The ticker continues and retries on the next interval.

  7. Minimal footprint — Docker resource limits cap the agent at 0.5 CPU and 256MB memory.

Project Structure​

ravenxcope-sensor-agent
main.go# Complete agent source (enrollment, heartbeat, metrics)
main_test.go# Unit tests for token persistence and host detection
go.mod# Go module definition and dependencies
go.sum# Dependency checksums
Dockerfile# Multi-stage build (Go builder → Alpine runtime)
.gitlab-ci.yml# CI/CD pipeline (build-dev on develop, build on main)
.gitignore# Git ignore rules
README.md# Quick-start guide