Skip to main content

Overview

The Ravenxcope Sensor is a single Go binary (ravenxcope-sensor) that runs on every sensor host. It is the only RavenXcope component that executes directly on sensor machines.

It supersedes two older components that used to be deployed separately:

  • ravenxcope-sensor-agent — the old enrollment + heartbeat agent.
  • the client mode of ravenxcope-sensor-suricata — the old eve.json relay.

Both are now folded into this one binary.

Responsibilities​

  1. Enrollment & PKI — Redeems a one-time claim code, enrolls with the Defense Center backend, and obtains an mTLS client certificate. See Enrollment & PKI.
  2. Suricata supervision — Launches and manages a local Suricata instance through a pluggable launcher (Docker or systemd). See Suricata Supervision.
  3. Alert relay — Reads Suricata eve.json from a unix socket, de-duplicates/queues events, and streams them over gRPC to the data collector. See Data Collector and the Data Plane scenario.
  4. Heartbeat — Periodically reports host metrics (CPU, memory, interfaces) to the backend. See Heartbeat & Configuration.
  5. Control — Maintains a NATS connection to receive backend commands (start/stop Suricata) and publish status. NATS carries control traffic only — never alert data.

Place in the architecture​

Internal package map​

PackageResponsibility
cmd/{enroll,run}.goCLI entrypoints: one-time enroll, long-running run (daemon).
internal/enrollmentClaim-code redeem + agent enroll HTTP client; CSR submission.
internal/pkiKey generation, CSR, mTLS certificate storage.
internal/suricatasocket_reader, parser, queue — read and de-duplicate eve.json.
internal/transportgRPC StreamManager (mTLS or insecure) to the data collector.
internal/launcherDetect() + Docker/systemd launchers that run Suricata locally.
internal/supervisorApplies NATS commands to the launcher; reports status.
internal/controlNATS client (commands in, status out).
internal/heartbeatCPU/memory/interface sampling via gopsutil.
internal/configEnv/flag configuration with file-over-env precedence.

Key design principles​

  1. Single binary, two modes — enroll runs once to onboard; run is the long-lived daemon.
  2. Claim-code onboarding only — enroll --code RXC-XXXX-YYYY-ZZZZ is the only supported entrypoint. Direct install-token configuration is intentionally unsupported.
  3. mTLS for data — alert streaming uses a client certificate issued during enrollment.
  4. Launcher auto-detection — adapts to the host without manual wiring (see Suricata Supervision).
  5. Resilient loops — failed heartbeats and transient stream errors are logged and retried, not fatal.