Alur Pendaftaran (Enrollment)

Pendahuluan

Pendaftaran (enrollment) adalah proses satu kali di mana agen sensor mendaftarkan dirinya ke backend, menukar token instalasi sementara dengan token sensor yang tahan lama. Dokumen ini menjelaskan siklus hidup pendaftaran lengkap, mulai dari pembuatan token di frontend hingga penyimpanan token persisten di host sensor.

---

Siklus Hidup Pendaftaran

---

Payload Permintaan Pendaftaran

Agen mengirimkan data berikut ke backend selama proses pendaftaran:

{
  "installToken": "one-time-token-from-frontend",
  "hostname": "sensor-ubuntu-host",
  "osInfo": "Ubuntu 24.04 LTS",
  "architecture": "x86_64",
  "agentVersion": "2.0.0",
  "sensorIp": "192.168.1.100",
  "sensorPort": 22,
  "sudoUser": "sensoradmin",
  "interfaces": [
    {
      "name": "enp130s0f0",
      "isManagement": true,
      "isLoopback": false,
      "isVirtual": false,
      "isWireless": false,
      "isUp": true,
      "bytesSent": 1073741824,
      "bytesRecv": 2147483648
    },
    {
      "name": "enp130s0f1",
      "isManagement": false,
      "isLoopback": false,
      "isVirtual": false,
      "isWireless": false,
      "isUp": true,
      "bytesSent": 0,
      "bytesRecv": 0
    }
  ]
}

Detail Field

Field	Sumber	Deskripsi
installToken	Variabel lingkungan INSTALL_TOKEN	Token satu kali yang dihasilkan oleh frontend
hostname	/host-hostname atau os.Hostname()	Nama host mesin, bukan nama host kontainer
osInfo	PRETTY_NAME dari /host-os-release	Nama OS host (misalnya, "Ubuntu 24.04 LTS")
architecture	runtime.GOARCH	Arsitektur CPU, dipetakan ke x86_64 / arm64
agentVersion	Konstanta 2.0.0	Versi perangkat lunak agen
sensorIp	UDP dial ke 8.8.8.8:80	IP keluar (outbound) utama dari host
sensorPort	Variabel env SENSOR_PORT (def: 22)	Port SSH untuk akses Ansible
sudoUser	Hardcoded sensoradmin	Pengguna untuk eskalasi hak istimewa (privilege)
interfaces	net.Interfaces() + gopsutil	Semua antarmuka jaringan dengan klasifikasinya

---

Respons Pendaftaran

{
  "success": true,
  "data": {
    "sensorId": "uuid",
    "sensorToken": "durable-token-for-heartbeats",
    "backendUrl": "http://10.10.10.70:5009",
    "heartbeatIntervalSeconds": 30
  }
}

Agen mengambil sensorToken dan heartbeatIntervalSeconds dari respons tersebut.

---

Persistensi Token

Setelah pendaftaran berhasil, persistSensorToken() menulis token yang tahan lama ke file konfigurasi (default: /etc/ravenxcope/sensor-agent.env):

Sebelum pendaftaran:

SENSOR_ID=sensor-1
INSTALL_TOKEN=install-token
BACKEND_URL=https://backend.local

Setelah pendaftaran:

SENSOR_ID=sensor-1
# INSTALL_TOKEN dikonsumsi selama pendaftaran
BACKEND_URL=https://backend.local
SENSOR_TOKEN=durable-token

Perilaku utama:

• Membuat direktori induk jika belum ada (os.MkdirAll).
• Jika SENSOR_TOKEN= sudah ada, nilainya akan diganti di tempat.
• Jika INSTALL_TOKEN= ada, akan dikomentari karena sudah dikonsumsi.
• Izin file diatur ke 0600 (hanya pemilik yang bisa baca/tulis).
• Jika persistensi gagal, agen mencatat peringatan tetapi tetap berjalan.

---

Deteksi Metadata Host

Agen mendeteksi metadata host menggunakan beberapa strategi agar berfungsi dengan benar di dalam kontainer Docker:

Nama Host (Hostname)

1. Membaca dari file yang dipasang (bind-mounted) pada variabel env HOST_HOSTNAME_FILE (default: /host-hostname)
2. Fallback ke os.Hostname()
3. Upaya terakhir: mengembalikan "unknown"

Informasi OS

1. Membaca PRETTY_NAME dari variabel env HOST_OS_RELEASE_FILE (default: /host-os-release)
2. Fallback ke /etc/os-release di dalam kontainer
3. Upaya terakhir: mengembalikan runtime.GOOS (misalnya, "linux")

IP Utama

Menggunakan UDP dial ke 8.8.8.8:80 (tidak ada lalu lintas aktual yang dikirim) untuk menentukan alamat IP lokal dari antarmuka rute default.

Arsitektur

Memetakan runtime.GOARCH ke nama yang mudah dibaca manusia:

• amd64 → x86_64
• arm64 → arm64

---

Mode Kegagalan

Skenario	Perilaku
INSTALL_TOKEN hilang pada startup pertama	Agen keluar dengan kesalahan fatal
Backend tidak terjangkau saat pendaftaran	Agen keluar dengan kesalahan fatal
Backend mengembalikan status non-200	Agen keluar dengan kesalahan fatal
Persistensi token gagal	Peringatan dicatat, agen berlanjut dengan token di memori
Agen restart dengan SENSOR_TOKEN yang sudah ada	Pendaftaran dilewati sepenuhnya