Enrollment & PKI

Onboarding a sensor is a one-time flow driven by a claim code and culminating in an mTLS client certificate the sensor uses to stream alerts.

Quick start

# 1. Install the package
sudo dpkg -i ravenxcope-sensor_<version>_amd64.deb

# 2. Enroll with a claim code (redeem -> enroll -> persist credentials)
sudo ravenxcope-sensor enroll \
  --code RXC-XXXX-YYYY-ZZZZ \
  --backend-url https://<defense-center>

# 3. Start the long-running service
sudo systemctl enable --now ravenxcope-sensor

enroll --code is the only supported onboarding entrypoint. Direct INSTALL_TOKEN configuration is intentionally unsupported.

---

Flow

Backend endpoints

Method & path	Purpose
POST /api/sensors/claim/redeem	Redeem a one-time claim code into a sensor identity / enrollment grant.
POST /api/sensors/{id}/agent/enroll	Submit CSR + host info; receive certPem and sensorToken.
POST /api/sensors/{id}/agent/heartbeat	Periodic host metrics (see Heartbeat).
POST /api/sensors/{id}/cert/renew	Renew the mTLS client certificate before expiry.
POST /api/sensors/{id}/revoke	Revoke a sensor (backend-side).

The enroll client (internal/enrollment/client.go) treats a non-200 response, an errors envelope, or an empty sensorToken as a failed enrollment and aborts.

---

PKI

• internal/pki generates the sensor key pair and CSR locally; the private key never leaves the host.
• The backend signs and returns certPem; the sensor persists cert + key + the durable sensorToken.
• The certificate is presented on the gRPC alert stream (mTLS). The backend's sensor-facing gRPC port enforces mTLS and re-checks the client-certificate serial against an active-sensor list during streaming — a revoked/inactive sensor's stream is cancelled.

Renewal: Use cert/renew ahead of expiry. A sensor with an expired or revoked certificate cannot stream alerts.