Skip to main content

Control Plane: Onboarding & Commanding a Sensor

This walkthrough follows a sensor from "nothing installed" to "running Suricata under backend control". It ties together the backend, the NATS Provisioner, and the unified Sensor.

The control plane never carries alert data — only trust (certificates, NATS credentials) and commands (start/stop). For the alert path, see the Data Plane scenario.

Actors​

ActorRole
OperatorA console user who creates the sensor record and a claim code.
FrontendReact SPA where the operator works.
Backend.NET API; issues claim codes, certs, and NATS credentials; sends commands.
PostgreSQLStores sensors, claim codes, and NATS account bookkeeping.
NATS ProvisionerSigns NATS account/user JWTs; stores encrypted seeds.
NATSMessage broker for commands/status.
Sensorravenxcope-sensor on the host.

Phase 1 — Claim and enroll​

Key facts:

  • The only supported onboarding entrypoint is enroll --code — there is no direct token configuration.
  • The CSR is generated locally; the private key never leaves the host. The backend returns a signed client certificate used for all later mTLS calls.
  • After this phase the sensor is enrolled and holds an mTLS identity.

Phase 2 — Provision NATS credentials​

The backend reconciles NATS credentials so the sensor can join the control bus.

Key facts:

  • The backend never signs JWTs; it always calls the provisioner with the shared secret.
  • Account creation is idempotent (create-or-return); the reconcile worker runs on an interval so transient provisioner outages self-heal.
  • The user's permissions are scoped to its own subjects: it may publish rxc.<tenant>.<sensor>.status and use its own JetStream consumer, and subscribe to _INBOX.> only.

Phase 3 — Connect, command, and supervise​

Key facts:

  • Commands ride the JetStream RXC_CMD stream (work-queue, durable per-sensor consumer cmd-<tenant>-<sensor>), so a briefly-offline sensor still receives them.
  • Status is core NATS fire-and-forget telemetry on rxc.<tenant>.<sensor>.status.
  • The sensor's internal/control client receives commands and hands them to internal/supervisor, which drives the internal/launcher to start/stop Suricata. See Sensor → Suricata Supervision.

End state​

The sensor now has: an mTLS certificate (for the data path), NATS credentials (for the control path), and a running Suricata instance. Alerts begin flowing — continue with the Data Plane scenario.