Sensor dan Sensor Virtual

Pendahuluan

Modul ini menangani pendaftaran sensor fisik, pendaftaran (enrollment) host satu kali, manajemen inventaris antarmuka, penyerapan heartbeat dan metrik host, serta manajemen siklus hidup sensor virtual. Sensor fisik adalah host perangkat keras, sedangkan sensor virtual adalah beban kerja (workload) Suricata yang dapat disebarkan dan mengonsumsi dua antarmuka yang memenuhi syarat pada host tersebut.

Orkestrasi sensor telah dipecah menjadi layanan-layanan yang terfokus:

• SensorsService — CRUD inti dan manajemen sensor
• SensorInterfaceAllocationService — Validasi kumpulan (pool) antarmuka jaringan
• ResilientHttpService — Circuit breaker + retry untuk panggilan HTTP eksternal
• VirtualSensorsService — Manajemen siklus hidup sensor virtual
• SensorHeartbeatService — Pemrosesan heartbeat

Semua controller mendelegasikan ke antarmuka layanan. Repositori (SensorRepository, SensorHeartbeatRepository, VirtualSensorRepository) menangani akses data.

---

Controller

Controller	Rute	Deskripsi
SensorsController	api/sensors	CRUD dan siklus hidup Sensor
VirtualSensorsController	api/virtual-sensors	Operasi sensor virtual
SensorHeartbeatController	api/sensor-heartbeat	Pemrosesan heartbeat

File:

• API/Controllers/Sensors/SensorsController.cs
• API/Controllers/Sensors/VirtualSensorsController.cs
• API/Controllers/Sensors/SensorHeartbeatController.cs

---

Entitas Sensor

File: Domain/Entities/Sensor.cs Tabel: sensors

Kolom	Tipe	Batasan	Deskripsi
id	uuid	PK	Kunci utama (UUIDv7)
name	varchar(255)	Wajib	Nama tampilan sensor
organization_id	uuid	FK, Wajib	Organisasi pemilik
status	varchar(50)	Wajib	unknown, off, on
operational_status	varchar(50)		active, inactive, maintenance
sensor_ip	varchar(50)	Bisa null	Alamat IP sensor
sensor_port	int	Bisa null	Nomor port sensor
sudo_user	varchar(100)	Bisa null	Pengguna sudo SSH untuk penyebaran
hostname	varchar(255)	Bisa null	Nama host yang dilaporkan agen sensor
os_info	varchar(255)	Bisa null	Informasi sistem operasi
architecture	varchar(100)	Bisa null	Arsitektur CPU yang dilaporkan
agent_version	varchar(100)	Bisa null	Versi agen host yang terinstal
enrollment_status	varchar(50)	Wajib	pending, enrolled
management_interface	varchar(255)	Bisa null	Antarmuka jaringan manajemen
last_heartbeat_at	timestamp	Bisa null	Heartbeat agen terakhir diterima
last_inventory_at	timestamp	Bisa null	Pembaruan inventaris antarmuka terakhir
created_at	timestamp		Stempel waktu pembuatan
updated_at	timestamp		Stempel waktu pembaruan terakhir

Properti Navigasi

[ForeignKey("OrganizationId")]
public Organization Organization { get; set; } = null!;
public ICollection<SensorHeartbeat> Heartbeats { get; set; }
public ICollection<VirtualSensor> VirtualSensors { get; set; }
public ICollection<SensorNetworkInterface> Interfaces { get; set; }

Model Status

Sensor memiliki dua dimensi status:

Status (konektivitas):

Nilai	Arti
unknown	Status awal, belum pernah terhubung
off	Sensor sedang offline
on	Sensor online dan melapor

Status Operasional (operasional):

Nilai	Arti
active	Operasi normal
inactive	Dinonaktifkan oleh administrator
maintenance	Sedang dalam pemeliharaan

---

Entitas Sensor Virtual

File: Domain/Entities/VirtualSensor.cs Tabel: virtual_sensors

Kolom	Tipe	Batasan	Deskripsi
id	uuid	PK	Kunci utama (UUIDv7)
sensor_id	uuid	FK, Wajib	Sensor induk
name	varchar(255)	Wajib	Nama sensor virtual
interface1	varchar(255)	Wajib	Antarmuka jaringan pertama
interface2	varchar(255)	Wajib	Antarmuka jaringan kedua
home_net	varchar(255)		CIDR jaringan rumah (def: 192.168.0.0/16)
status	varchar(50)	Wajib	Status siklus hidup
activation_status	varchar(50)	Bisa null	Status aktivasi Ansible
activation_error	text	Bisa null	Pesan kesalahan aktivasi gagal
execution_id	varchar(255)	Bisa null	ID eksekusi Ansible
deployment_path	varchar(255)	Bisa null	Jalur target penyebaran
created_at	timestamp		Stempel waktu pembuatan
updated_at	timestamp		Stempel waktu pembaruan terakhir

Model Status Sensor Virtual

Status (siklus hidup):

Nilai	Arti
inactive	Dibuat tetapi belum diaktivasi
activating	Aktivasi sedang berlangsung via Ansible
active	Berhasil diaktivasi dan berjalan
failed	Aktivasi gagal

Status Aktivasi (eksekusi Ansible):

Nilai	Arti
pending	Antre untuk aktivasi
running	Playbook Ansible sedang berjalan
success	Aktivasi selesai dengan sukses
failed	Aktivasi gagal (lihat kesalahan)

---

Entitas Heartbeat Sensor

File: Domain/Entities/SensorHeartbeat.cs Tabel: sensor_heartbeats

Kolom	Tipe	Batasan	Deskripsi
id	uuid	PK	Kunci utama (UUIDv7)
sensor_id	uuid	FK, Wajib	Sensor yang melapor
last_seen	timestamp	Bisa null	Stempel waktu terakhir terlihat
isActive	bool	Bisa null	Bendera aktif
created_at	timestamp		Stempel waktu pembuatan
updated_at	timestamp		Stempel waktu pembaruan terakhir

---

Tanggung Jawab Sensor

Registrasi dan Pendaftaran (Enrollment)

• Membuat draf sensor dengan nama dan organisasi
• Menghasilkan perintah instalasi satu kali dari UI
• Menginstal satu agen host pada sensor fisik
• Mendaftarkan sensor dan menyimpan metadata host plus inventaris antarmuka terstruktur

Orkestrasi Aktivasi

• Mengaktifkan atau menonaktifkan sensor virtual melalui layanan Ansible
• Melacak progres dan status aktivasi
• Menyebarkan hanya Suricata dan sensor-client untuk setiap sensor virtual

Pemrosesan Heartbeat

• Menerima laporan heartbeat dari agen host
• Memperbarui last_heartbeat_at dan last_inventory_at pada sensor
• Menyimpan status online di InfluxDB sensor_status
• Menyimpan CPU host, memori, dan lalu lintas antarmuka yang layak di InfluxDB sensor_metrics

---

Tanggung Jawab Sensor Virtual

Manajemen Siklus Hidup

• Membuat sensor virtual yang terikat pada sensor fisik
• Mengonfigurasi pasangan antarmuka (interface1, interface2) dan jaringan rumah
• Melacak jalur penyebaran dan status eksekusi

Aktivasi via Ansible

• Mengirimkan permintaan aktivasi ke layanan Ansible di AnsibleSettings:ServiceUrl
• Meneruskan konfigurasi termasuk:
  • Penetapan antarmuka
  • Detail koneksi InfluxDB
  • Titik akhir pengumpul data (data collector)
  • Kredensial registri Docker
  • URL Backend untuk callback

Alokasi Antarmuka

• Antarmuka disimpan sebagai rekaman terstruktur pada sensor induk
• Pembuatan sensor virtual memerlukan dua antarmuka eksplisit
• Hanya antarmuka yang ditandai isEligible=true yang dapat ditetapkan
• Status penetapan dilacak pada rekaman antarmuka itu sendiri

---

Dependensi Eksternal

Dependensi	Kunci Konfigurasi	Tujuan
Layanan Ansible	AnsibleSettings:ServiceUrl	Penyebaran sensor virtual
API Key Sensor	SensorApiSettings:ApiKey	Autentikasi pemicu sensor
URL Backend	BackendUrl	URL Callback untuk Ansible
Pengumpul Data	DataCollector:Endpoint/Port	Tujuan data sensor
Registri Docker	DockerRegistry:Registry/User/Pass	Sumber gambar kontainer
InfluxDB	InfluxDb:*	Aliran metrik dan heartbeat

Pengaturan ini digabungkan ke dalam SensorRuntimeOptions untuk kenyamanan:

public sealed class SensorRuntimeOptions
{
    public string BackendUrl { get; set; }
    public string SensorApiKey { get; set; }
    public string AnsibleServiceUrl { get; set; }
    public string InfluxDbUrl { get; set; }
    public string InfluxDbToken { get; set; }
    public string InfluxDbOrg { get; set; }
    public string InfluxDbBucket { get; set; }
    public string DataCollectorEndpoint { get; set; }
    public string DataCollectorPort { get; set; }
    public string DockerRegistry { get; set; }
    public string DockerUsername { get; set; }
    public string DockerPassword { get; set; }
}

---

Layanan gRPC Healthcheck

File: Infrastructure/Services/SensorHealthcheckService.cs Proto: Protos/sensor_healthcheck.proto

Menyediakan titik akhir gRPC untuk sensor melaporkan status kesehatan. Dipetakan dalam pipa middleware:

app.MapGrpcService<SensorHealthcheckService>();

---

Aturan Cascade Delete

Induk → Anak	Perilaku
Organisasi → Sensor	Cascade
Sensor → SensorHeartbeat	Cascade
Sensor → VirtualSensor	Cascade

---

Area Risiko Utama

Area	Risiko
Orkestrasi aktivasi	Alur multi-langkah bergantung pada kontrak respons Ansible eksternal
Tanpa tes integrasi	Jalur aktivasi kritis kekurangan cakupan pengujian
MonitorExecutionAsync	Task.Run bersifat fire-and-forget untuk memantau status eksekusi Ansible — tidak ada pelaporan kesalahan jika pemantauan gagal

---

Status Refactoring

Selesai

1. Memecah layanan orkestrasi sensor menjadi layanan-layanan yang terfokus.
2. Menambahkan penanganan siklus hidup VirtualSensorsService khusus.
3. Menambahkan jalur eksekusi keluar yang resilien untuk interaksi Ansible.
4. Memindahkan logika alokasi antarmuka ke layanan khusus.
5. Menjaga controller tetap fokus pada transport dan delegasi.

Terbuka

1. Menambahkan tes integrasi untuk alur aktivasi dan rollback.