wazuh-telegram-soc — Alert Wazuh Dipilah per Topic Telegram

wazuh-telegram-soc adalah router alert yang saya buat untuk tim SOC di tempat saya bekerja. Sebelumnya, semua alert Wazuh dikirim ke satu channel Telegram. Alert kritis, temuan CVE, dan notifikasi rutin bercampur di satu tempat, sehingga alert yang benar-benar perlu ditindaklanjuti gampang tenggelam.

Router ini memindahkan alert ke grup Telegram yang memakai fitur Topics. Setiap kategori punya ruangnya sendiri, mulai dari Critical, High, akses privileged, dan kesehatan agent sampai CVE, perubahan file, compliance, dan laporan harian. Alert penting tetap datang dalam hitungan detik, sedangkan kategori yang ramai dikirim sebagai ringkasan berkala. Channel lama tidak diubah dan tetap berfungsi sebagai arsip.

Kenapa Tidak Memakai Integrasi Bawaan

Wazuh sebenarnya sudah punya fitur integrasi untuk mengirim alert ke layanan luar. Untuk kebutuhan ini, ada dua kendala.

• Integrasi bawaan menjalankan satu proses skrip untuk setiap alert yang lolos filter. Saat volume tinggi, proses itu mengantre dan ikut menahan integrasi lain yang sudah berjalan.
• Telegram membatasi bot sekitar 20 pesan per menit untuk satu grup, padahal satu sumber yang sedang banjir, misalnya agent dengan disk penuh, bisa menghasilkan ribuan alert dalam beberapa menit.

Jadi alert tidak mungkin dikirim satu per satu. Yang dibutuhkan adalah penyaring: alert penting dikirim saat itu juga, pengulangan digabung, dan sisanya diringkas.

Cara Kerjanya

Router berjalan sebagai service systemd terpisah di server Wazuh manager dan hanya membaca data. Konfigurasi Wazuh tidak perlu diubah dan manager tidak perlu di-restart.

1. Membaca baris baru di alerts.json secara streaming, mirip tail -F. Posisi baca disimpan, jadi aman saat berkas dirotasi tengah malam maupun saat service di-restart.
2. Mengelompokkan setiap alert dengan aturan berurutan berdasarkan rule group, rule ID, dan level. Aturan pertama yang cocok menentukan topic tujuannya.
3. Alert untuk topic real-time masuk buffer yang dikirim setiap 20 detik, sedangkan alert untuk topic ringkasan masuk akumulator yang dikirim sesuai jadwal.
4. Semua pesan melewati antrian berprioritas dengan pembatas laju sebelum dikirim ke Telegram Bot API.

Pembagian Topic

Topic General diganti namanya menjadi Diskusi Tim untuk koordinasi, lengkap dengan panduan yang disematkan. Aktivitas sudo sengaja punya topic sendiri karena pekerjaan admin sehari-hari cukup sering memicunya, dan topic Critical sebaiknya tidak tenggelam oleh hal rutin.

Real-time Tanpa Spam

• Kalau dalam satu jeda 20 detik hanya ada satu atau dua alert, masing-masing dikirim lengkap: agent, IP sumber dan tujuan, user, command, teknik MITRE ATT&CK, serta potongan log asli dalam blok yang bisa dibuka-tutup. Kalau lebih dari itu, alert digabung menjadi satu daftar ringkas.
• Alert dengan rule dan agent yang sama hanya dikabari sekali per jendela waktu: 15 menit untuk Critical, 60 menit untuk High, dan 30 menit untuk perintah sudo yang sama. Setelah jendelanya habis, jumlah pengulangannya dilaporkan bersama IP atau user yang paling sering muncul.
• Alert yang baru terbaca lebih dari 15 menit setelah kejadian, misalnya sesudah service di-restart, dialihkan ke ringkasan. Kelebihan alert saat terjadi flood juga diperlakukan sama, jadi tidak ada alert yang hilang tanpa jejak.
• Tim membalas alert di topic Critical dan High dengan ACK, INVESTIGASI, atau FP supaya jelas siapa yang sedang menangani apa.

Ringkasan yang Tetap Bisa Ditindaklanjuti

• CVE dikelompokkan per paket, lengkap dengan jumlah CVE unik Critical dan High serta host yang terdampak. CVE dengan skor CVSS tertinggi diberi tautan ke NVD, ditambah hitungan CVE Medium, Low, dan yang sudah resolved.
• FIM menampilkan per host berapa file yang diubah, ditambah, dan dihapus, beserta path yang paling sering berubah, termasuk registry Windows.
• SCA menampilkan check yang berubah dari passed ke failed maupun sebaliknya, beserta skor terbaru tiap host.
• Medium dan Informational menampilkan rule dan agent teratas, sehingga sumber yang sedang banjir langsung kelihatan.
• Laporan harian merangkum total alert per severity di luar CVE, statistik CVE, rule dan agent teratas, agent yang sempat terputus, dan jumlah notifikasi yang terkirim ke tiap topic.

Aturan yang Bisa Diubah Lewat Config

Semua aturan routing ada di config. Untuk menggeser kategori, mengubah jadwal ringkasan, atau mengabaikan rule tertentu, cukup edit config lalu restart service. Potongannya kira-kira seperti ini:

{
  "routes": [
    { "topic": "cve", "mode": "digest",
      "match": { "groups_any": ["vulnerability-detector"] } },
    { "topic": "critical", "mode": "realtime",
      "match": { "level_min": 12 } },
    { "topic": "high", "mode": "realtime",
      "match": { "level_min": 10 } },
    { "topic": "medium", "mode": "digest",
      "match": { "level_min": 7 } },
    { "topic": "info", "mode": "digest", "match": {} }
  ]
}

Urutan aturan menentukan hasilnya. Karena aturan CVE ada di paling atas, alert CVE berlevel 13 tetap masuk ringkasan CVE dan tidak membanjiri topic Critical.

Menjaga Batas Telegram

• Critical selalu didahulukan di antrian. Laju kirim dijaga maksimal 18 pesan per menit dengan jeda minimal 1,2 detik antarpesan.
• Kalau Telegram membalas 429, router menunggu sesuai nilai retry_after. Kalau jaringan atau server Telegram bermasalah, router mencoba lagi dengan jeda yang makin panjang.
• Ukuran antrian dibatasi. Kalau penuh, yang dilepas lebih dulu adalah pesan berprioritas paling rendah yang paling lama menunggu.
• Ada jalur cadangan untuk kasus yang jarang terjadi. Pesan untuk topic yang terhapus dikirim ke Diskusi Tim dengan label topic aslinya, format HTML yang ditolak dikirim ulang sebagai teks biasa, dan ID grup yang berubah setelah di-upgrade ke supergroup diikuti otomatis.

Tahan Restart dan Rotasi Log

• Posisi baca, isi ringkasan yang belum terkirim, dan antrian pesan disimpan ke berkas state setiap menit dengan penulisan atomik. Setelah restart, ringkasan tidak hilang dan alert lama tidak terkirim dua kali.
• Pembaca berkas mengikuti rotasi harian lewat perubahan inode, mendeteksi berkas yang terpotong, dan menunda baris yang belum utuh.
• Watchdog mengirim peringatan kalau alerts.json tidak bertambah selama 30 menit, karena itu tanda pipeline Wazuh sedang berhenti. Kabar susulan dikirim begitu alert mengalir lagi.
• Hanya satu instance yang boleh berjalan, dan setiap akumulator punya batas jumlah rule, agent, dan path supaya pemakaian memori tetap terkendali.

Keamanan

• Service berjalan sebagai user wazuh dan hanya membaca alert. Unit systemd-nya diperketat dengan NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, batas memori, dan izin tulis hanya ke folder state.
• Config yang berisi token bot disimpan dengan izin 640 root:wazuh, dan token selalu disensor dari pesan log.
• Isi alert diperlakukan sebagai data tak tepercaya karena isi log di endpoint bisa diatur penyerang. Semua teks di-escape sebelum masuk format HTML Telegram, tautan hanya dibuat untuk ID CVE yang lolos validasi, dan pratinjau tautan dimatikan.
• Anggota grup tidak bisa membuat topic, menyematkan pesan, mengubah info grup, atau mengundang orang. Topic ringkasan ditutup, jadi hanya bot dan admin yang bisa menulis di sana.

Grup Ditata Lewat Kode

Perintah setup-group menata grup lewat Bot API dalam sekali jalan. Perintah ini membuat 10 topic lengkap dengan ikon, mengganti nama General, menyematkan panduan di setiap topic, menutup topic ringkasan, mengatur izin anggota dan deskripsi grup, lalu menyimpan ID setiap topic ke config. Topic yang sudah ada dilewati, jadi perintahnya aman dijalankan ulang.

Pengujian

• 35 selftest tanpa jaringan, meliputi routing contoh alert, dedup, pengalihan alert terlambat, validitas HTML dan panjang pesan, pemecahan pesan panjang, jadwal ringkasan, simpan dan muat state, serta pembacaan berkas saat ada baris parsial, berkas terpotong, dan rotasi.
• Contoh alert sintetis yang meniru struktur alert Wazuh 4.x dipakai untuk mempratinjau semua format pesan lewat mode replay --dry-run tanpa mengirim apa pun.
• Perintah check memeriksa config, koneksi bot, status admin di grup, dan akses ke alerts.json. Installer menjalankan selftest dan check sebagai user wazuh sebelum service dinyalakan.
• Pengiriman ke setiap topic diuji langsung, termasuk ke topic yang ditutup.

Teknologi

Ditulis dengan Python 3 (kompatibel mulai 3.8) dan hanya memakai standard library, jadi bisa berjalan dengan Python bawaan Wazuh tanpa pip install. Integrasinya memakai Telegram Bot API dengan Forum Topics, format HTML, dan blockquote yang bisa dibuka-tutup. Programnya satu berkas sekitar 2.000 baris dengan perintah run, check, test, replay, setup-group, dan selftest, ditambah unit systemd dan installer Bash.

Kode sumbernya privat karena terhubung dengan lingkungan kerja.