Konfigurasi dan Penyebaran

Pendahuluan

Dokumen ini mencakup variabel lingkungan, penyebaran Docker, integrasi Ansible, pipa CI/CD, dan pemecahan masalah untuk agen sensor.

---

Variabel Lingkungan

Variabel	Wajib	Default	Deskripsi
SENSOR_ID	Ya	—	UUID sensor, diberikan oleh backend saat sensor dibuat
BACKEND_URL	Ya	—	URL basis API Backend (misalnya, http://10.10.10.70:5009)
INSTALL_TOKEN	Entri awal	—	Token pendaftaran satu kali yang dihasilkan oleh frontend
SENSOR_TOKEN	Setelah reg	—	Token tahan lama hasil pendaftaran, disimpan di file konfigurasi
HEARTBEAT_INTERVAL	Tidak	30	Interval heartbeat dalam detik
SENSOR_PORT	Tidak	22	Port SSH pada host sensor (dilaporkan ke backend untuk akses Ansible)
CONFIG_FILE	Tidak	/etc/ravenxcope/sensor-agent.env	Jalur di mana token sensor disimpan secara persisten
HOST_OS_RELEASE_FILE	Tidak	/host-os-release	Bind-mount host /etc/os-release untuk deteksi OS
HOST_HOSTNAME_FILE	Tidak	/host-hostname	Bind-mount host /etc/hostname untuk deteksi nama host

---

Penyebaran Docker

Build Image

docker build -t sensor-agent:latest .

Dockerfile menggunakan build multi-tahap:

1. Tahap Builder (golang:1.22-alpine):

   • Mengunduh dependensi modul Go.
   • Membangun binary statis dengan CGO_ENABLED=0.

2. Tahap Runtime (alpine:latest):

   • Menyalin binary statis.
   • Menambahkan ca-certificates untuk dukungan HTTPS.
   • Berjalan sebagai root (diperlukan untuk enumerasi antarmuka jaringan).

Jalankan dengan Docker

docker run -d \
  --name sensor-agent \
  --restart unless-stopped \
  --network host \
  -v /etc/os-release:/host-os-release:ro \
  -v /etc/hostname:/host-hostname:ro \
  -v /etc/ravenxcope:/etc/ravenxcope \
  -e SENSOR_ID=your-sensor-uuid \
  -e BACKEND_URL=http://10.10.10.70:5009 \
  -e INSTALL_TOKEN=one-time-token \
  -e HEARTBEAT_INTERVAL=30 \
  --deploy-resources-limits-cpus=0.5 \
  --deploy-resources-limits-memory=256M \
  sensor-agent:latest

Bendera Docker utama:

Bendera	Tujuan
--network host	Diperlukan untuk deteksi antarmuka jaringan host yang akurat
-v /etc/os-release:/host-os-release:ro	Deteksi OS host alih-alih OS kontainer
-v /etc/hostname:/host-hostname:ro	Deteksi nama host alih-alih nama host kontainer
-v /etc/ravenxcope:/etc/ravenxcope	Penyimpanan persisten untuk token sensor
--restart unless-stopped	Restart otomatis setelah host dinyalakan ulang (reboot)

Docker Compose

Agen adalah bagian dari stack sensor dalam docker-compose.yml:

sensor-agent:
  image: exdec/sensor-agent:latest
  restart: unless-stopped
  network_mode: host
  volumes:
    - /etc/os-release:/host-os-release:ro
    - /etc/hostname:/host-hostname:ro
    - /etc/ravenxcope:/etc/ravenxcope
  env_file:
    - .env.sensor-agent
  deploy:
    resources:
      limits:
        cpus: "0.5"
        memory: 256M

---

Integrasi Ansible

Agen sensor disebarkan secara otomatis melalui Ansible ketika sensor diaktivasi dari frontend. Playbook Ansible:

1. Terhubung ke host sensor melalui SSH.
2. Membuat file .env.sensor-agent dengan konfigurasi yang tepat.
3. Menarik (pull) dan menjalankan kontainer Docker.
4. Memverifikasi agen sedang berjalan.

Contoh task Ansible:

- name: Create sensor agent env file
  copy:
    dest: /opt/sensor/.env.sensor-agent
    content: |
      SENSOR_ID={{ sensor_uuid }}
      BACKEND_URL={{ backend_url }}
      INSTALL_TOKEN={{ install_token }}
      HEARTBEAT_INTERVAL=30

Setelah agen terdaftar, INSTALL_TOKEN dikonsumsi dan SENSOR_TOKEN disimpan secara persisten. Restart kontainer berikutnya tidak memerlukan token instalasi.

---

Pipa CI/CD

Pipa GitLab CI memiliki dua tahap:

Tahap	Branch	Image Tag
build-dev	develop	latest-dev, <commit-sha>
build	main	latest, <commit-sha>

Kedua tahap:

1. Login ke GitLab Container Registry.
2. Membangun image multi-platform (linux/amd64) menggunakan docker buildx.
3. Mendorong (push) dengan tag latest* dan commit SHA.

---

Menjalankan Tes

cd ravenxcope-sensor-agent
go test -v ./...

Cakupan tes saat ini:

Tes	Verifikasi
TestPersistSensorTokenCreatesMissingConfigFile	Persistensi token membuat direktori induk dan menulis dengan benar
TestPersistSensorTokenUpdatesExistingConfigFile	Penggantian token dan pengomentaran INSTALL_TOKEN berfungsi pada konfigurasi yang ada
TestOsInfoFromFilesPrefersHostMetadata	File rilis OS host diutamakan daripada rilis OS kontainer
TestHostnameFromFilesPrefersHostMetadata	File nama host host diutamakan daripada nama host kontainer

---

Membangun dari Sumber (Source)

# Instal Go 1.22+
go mod download
go build -o sensor-agent .

# Jalankan secara lokal
export SENSOR_ID=test-sensor-uuid
export BACKEND_URL=http://localhost:5009
export INSTALL_TOKEN=test-install-token
export HEARTBEAT_INTERVAL=5
./sensor-agent

---

Pemecahan Masalah

Agen keluar dengan "SENSOR_ID is required"

Variabel lingkungan SENSOR_ID hilang. Ini adalah UUID yang diberikan oleh backend saat sensor dibuat di frontend.

Agen keluar dengan "INSTALL_TOKEN is required for first enrollment"

Pada startup pertama, agen membutuhkan token instalasi untuk mendaftar. Token ini dihasilkan dari halaman detail sensor di frontend ("Generate Install Command").

Agen mencatat "heartbeat failed" berulang kali

1. Periksa konektivitas backend:

   curl -v http://<BACKEND_URL>/api/sensors/<SENSOR_ID>/agent/heartbeat

2. Periksa apakah token sensor valid — mungkin telah dicabut di backend.
3. Periksa konektivitas jaringan dari host sensor ke pusat pertahanan.

Agen melaporkan nama host atau OS yang salah

Agen membaca metadata host dari file yang dipasang secara bind-mount. Verifikasi volume telah terpasang:

docker inspect sensor-agent | grep -A5 Mounts

Mount yang diharapkan:

• /etc/os-release → /host-os-release (read-only)
• /etc/hostname → /host-hostname (read-only)

Agen hanya menunjukkan antarmuka kontainer

Agen harus dijalankan dengan --network host untuk melihat antarmuka jaringan host. Verifikasi:

docker inspect sensor-agent --format '{{.HostConfig.NetworkMode}}'
# Diharapkan: host

Token sensor tidak tersimpan setelah restart

Periksa pemasangan volume /etc/ravenxcope:

cat /etc/ravenxcope/sensor-agent.env

File tersebut harus berisi SENSOR_TOKEN=... setelah pendaftaran berhasil. Jika tidak ada, volume mungkin tidak terpasang, dan agen akan mendaftar ulang pada setiap restart.