Membuat konektor kustom

Didukung di:

Google secops SOAR

Catatan: Dokumen ini mengasumsikan bahwa Anda memiliki pengetahuan dasar tentang Python dan pemrograman berorientasi objek.

Gunakan dokumen ini untuk mempelajari cara SOAR SDK membangun integrasi kustom untuk alat pihak ketiga yang mungkin tidak tersedia di Hub Konten. Konektor digunakan untuk menyerap data dari sumber data yang biasanya, tetapi tidak selalu, memiliki semacam antrean pemberitahuan. Kasus, pemberitahuan, dan peristiwa dibuat di platform menggunakan interaksi konektor dengan aplikasi Google SecOps. Konektor akan menyerap data peristiwa dasar, menetapkan data tersebut ke pemberitahuan, lalu mengirimkan pemberitahuan ke aplikasi Google SecOps dan Pipeline Pemrosesan Datanya.

Catatan: Pelajari lebih lanjut library Umum TIP.

Untuk membuat konektor kustom, ikuti langkah-langkah umum berikut:

1. Buat class Manager yang berisi logika API untuk alat pihak ketiga.
2. Bangun konektor menggunakan IDE.

Buat Pengelola

Langkah pertama dalam membuat konektor adalah membangun class Manager yang berisi semua logika API yang diperlukan untuk teknologi yang Anda integrasikan. Sebagai contoh, integrasi Netskope di Google SecOps mencakup Pengelola bawaan. Pengelola ini berisi semua logika yang diperlukan untuk berinteraksi dengan Netskope API, dan dapat digunakan sebagai model untuk penerapan Anda sendiri.

Buat Konektor

Di IDE, buat konektor baru dengan mengikuti petunjuk di Membangun Integrasi Kustom. IDE akan membuat template generik yang menyertakan komentar kode yang menjelaskan struktur dan persyaratan dasar skrip konektor.

Meskipun logika konektor dapat bervariasi, prosesnya umumnya mencakup langkah-langkah inti berikut:

1. Gunakan API alat pihak ketiga untuk mengambil pemberitahuan, deteksi, atau peristiwa. Untuk Netskope, hal ini ditangani oleh metode get_alerts(). Untuk memastikan pemberitahuan tidak diduplikasi, kirim kueri menurut stempel waktu dan perbarui setelah setiap operasi.
2. Buat pemberitahuan menggunakan class AlertInfo (sebelumnya CaseInfo), dengan menetapkan semua kolom yang diperlukan
3. Ambil dan ratakan data peristiwa terkait untuk mencegah masalah pada daftar dan kamus bertingkat, lalu tambahkan peristiwa yang diratakan ke pemberitahuan.
4. Urutkan pemberitahuan menurut waktu dan simpan stempel waktu terbaru untuk digunakan dalam kueri berikutnya.

Catatan: Pemberitahuan dapat berisi beberapa peristiwa. Misalnya, platform SIEM mengorelasikan beberapa peristiwa menjadi satu alarm (seperti Trellix ESM) atau pelanggaran (seperti QRadar). Sebaliknya, alat deteksi endpoint biasanya menghasilkan satu peristiwa per pemberitahuan. Logika konektor Anda harus mencerminkan struktur sumber data.

Impor dan SDK

Setiap konektor harus melakukan hal berikut:

• Impor class SiemplifyConnectorExecution dari SiemplifyConnectors. Class ini biasanya di-instantiate dalam fungsi main() konektor. Skrip berakhir saat objek ini meneruskan daftar pemberitahuan ke aplikasi Google SecOps menggunakan metode return_package().
• Impor class AlertInfo dari SiemplifyConnectorsDataModel. Membuat instance class ini akan membuat objek pemberitahuan. Dalam contoh ini, namanya diubah menjadi SiemplifyAlertInfo untuk menghindari kebingungan dengan objek pemberitahuan bawaan sistem sumber (Netskope), yang dalam kasus ini penggantian nama bersifat opsional.

Modul SiemplifyUtils menyediakan metode yang umum digunakan untuk mencatat aktivitas, menangani format data, konversi waktu, dan lainnya. Sebaiknya impor output_handler, dict_to_flat, dan unix_now, karena ketiganya penting untuk fungsi inti, termasuk penanganan waktu.

Sebagian besar konektor juga mengimpor class Manager integrasi. Beberapa integrasi menyertakan lebih dari satu Pengelola. Library Python standar tambahan juga dapat diimpor, bergantung pada kasus penggunaan Anda.

Catatan: Konektor lama dapat menggunakan CaseInfo dari SiemplifyConnectors. Class ini sama dengan AlertInfo dan mencerminkan konvensi penamaan yang tidak digunakan lagi.

Variabel konstanta

Sebaiknya deklarasikan beberapa variabel konstanta untuk digunakan nanti.

Gambar 1: Variabel konstanta

Contoh skrip untuk membuat notifikasi Google SecOps

Peringatan dibuat dengan membuat instance objek class AlertInfo seperti yang dibahas sebelumnya. Dalam contoh ini, namanya diubah menjadi SiemplifyAlertInfo() untuk menghindari kebingungan dengan sistem sumber. Objek alert_info mencakup beberapa properti wajib yang harus ditentukan agar aplikasi dapat memproses pemberitahuan dengan benar. Fungsi build_alert_info menerima pemberitahuan Netskope (dalam format JSON mentah, diterima dari API) dan objek Siemplify sebagai input. Kemudian, skrip ini akan mem-parsing pemberitahuan Netskope dan menetapkan nilai yang relevan ke kolom `alert_info`.

Fungsi ini juga menggunakan konstanta yang ditentukan sebelumnya. Semua properti yang ditetapkan pada objek alert_info menjadi bagian dari objek pemberitahuan dalam aplikasi Google SecOps.

Baris 35 (pada Gambar 2) menyoroti bagian penting dari proses ini: pemberitahuan diratakan menggunakan metode dict_to_flat, lalu ditambahkan ke properti events.

Gambar 2: Contoh skrip untuk membuat pemberitahuan

 

Peringatan dapat berisi beberapa peristiwa. Jika demikian, Anda harus menyertakan logika untuk menangani setiap peristiwa dengan tepat. Dalam contoh ini, setiap notifikasi hanya berisi satu peristiwa, sehingga penerapan default sudah cukup.

Metode dict_to_flat digunakan untuk meratakan struktur JSON mentah. Hal ini membantu menghindari masalah pada daftar dan kamus bertingkat. Pasangan nilai kunci yang diratakan adalah versi asli yang sedikit dimodifikasi.

Tinjau logika berikut dalam Gambar 2:

• display_id diberi nilai yang dibuat secara acak menggunakan library uuid. Peringatan Netskope tidak menyediakan kolom UUID, tetapi jika tersedia, kolom tersebut dapat digunakan sebagai gantinya.
• ticket_id disetel agar cocok dengan display_id. Kedua kolom harus unik per pemberitahuan dalam sistem. Keunikan ini dipastikan dengan membuat UUID acak.
• name adalah Nama Pemberitahuan dan akan ditampilkan di GUI.
• rule_generator merujuk pada aturan yang menghasilkan notifikasi dalam sistem sumber. Kolom ini mungkin tidak selalu ada dalam data mentah. Jika tidak ada, Anda dapat menetapkan nilai string apa pun, tetapi tidak boleh dibiarkan kosong.
• start_time dan end_time mewakili stempel waktu pemberitahuan. Dalam contoh ini, notifikasi Netskope memberikan stempel waktu epoch Unix, yang harus dikalikan dengan 1.000 untuk mengonversinya menjadi milidetik. Ini adalah format yang diharapkan untuk Google SecOps. Jika sumber menggunakan format yang berbeda, Anda harus mengonversinya. Lihat modul SiemplifyUtils.py untuk mengetahui metode konversi waktu yang berguna.
• priority: aplikasi Google SecOps menetapkan Prioritas untuk setiap kasus berdasarkan prioritas pemberitahuannya. Google SecOps API memetakan nilai numerik ke label visual menggunakan skema berikut, dengan nilai bilangan bulat diteruskan di konektor: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100} dengan nilai bilangan bulat adalah nilai yang diteruskan di Konektor. Misalnya, meneruskan `100` akan menandai pemberitahuan sebagai Kritis di GUI. Di konektor ini, fungsi helper tambahan memetakan nilai tingkat keparahan Netskope ke skala prioritas ini menggunakan konstanta `SEVERITY_MAP`. Namun, karena kolom tingkat keparahan Netskope tidak konsisten, pemetaan memerlukan logika tambahan untuk mengevaluasi beberapa kolom.
• device_vendor dan device_product diberi nilai dari konstanta yang ditentukan sebelumnya dalam skrip.
• environment sangat penting saat menggunakan beberapa lingkungan di SecOps Google. Dalam hal ini, nilai tersebut berasal dari objek siemplify dan selaras dengan lingkungan yang dipilih untuk konektor di platform.
• Di Baris 37 (Gambar 3), konektor mengubah kamus peristiwa dasar dengan menambahkan kunci baru, product_name, dengan nilai `"Netskope"`. Hal ini diperlukan karena data mentah tidak menyertakan kolom produk yang konsisten yang dapat digunakan untuk pemetaan dan pemodelan dalam ontologi platform.

  

  Gambar 3: Mengubah peristiwa dasar

Contoh skrip untuk menjalankan Konektor

Fungsi main berisi logika eksekusi inti untuk konektor:

• Dekorator output_handler digunakan untuk tujuan proses debug dan tidak dibahas dalam dokumen ini.
• Fungsi main menyertakan parameter opsional, is_test_run, yang secara default ditetapkan ke False. Seperti namanya, parameter ini menentukan apakah konektor harus menyerap pemberitahuan dalam produksi atau berjalan dalam mode pengujian dari tab Pengujian Konektor di aplikasi.

Tinjau perincian logika eksekusi inti per baris skrip:

Gambar 3: Mengubah peristiwa dasar

• Baris 56 dan 57 melakukan inisialisasi dua daftar kosong yang digunakan selama eksekusi.
• Di baris 58, class SiemplifyConnectorExecution membuat instance objek siemplify. Objek ini mengelola sebagian besar perilaku runtime konektor.
• Di baris 61, instance Connector Allowlist dibuat. Meskipun tidak digunakan dalam konektor ini, biasanya digunakan dalam konektor lain dan tidak dibahas dalam panduan ini.
• Di baris 67–69, variabel ditentukan untuk parameter konektor, seperti kredensial autentikasi atau setelan konfigurasi.
• Di baris 71, objek NetskopeManager di-instantiate dan parameter yang relevan diteruskan untuk mengaktifkan autentikasi yang berhasil. Logika Manager internal yang menangani autentikasi tidak ditampilkan dalam contoh ini.
• Di baris 73, kode mengambil stempel waktu dari file lokal yang dibuat selama eksekusi konektor sebelumnya. Stempel waktu ini digunakan untuk menghindari pemrosesan ulang pemberitahuan yang sama.
• Di baris 74 dan 75, fungsi ini menangani kasus saat konektor berjalan untuk pertama kalinya dan stempel waktu belum ditetapkan (misalnya, saat defaultnya adalah `0`). Karena Netskope memerlukan waktu epoch Unix dan tidak menerima `0` sebagai waktu mulai yang valid, fungsi `unix_now` digunakan untuk mengambil waktu saat ini dalam milidetik. Nilai ini dibagi dengan `1.000` untuk mengonversinya menjadi detik epoch Unix. Waktu mulai dan berakhir yang dihasilkan kemudian diteruskan ke metode `get_alerts` di Pengelola. Meskipun banyak API hanya menerima waktu mulai, Netskope API memerlukan waktu mulai dan waktu berakhir untuk kueri pemberitahuan berbasis waktu.
Catatan: Penanganan waktu dan stempel waktu adalah salah satu aspek paling rumit dalam membangun konektor. Sistem pihak ketiga yang berbeda menampilkan stempel waktu dalam berbagai format, dan beberapa sistem mungkin tidak mendukung kueri berdasarkan format yang sama dengan yang ditampilkan. Pemahaman menyeluruh tentang API sistem sumber sangat penting.
• Di baris 77, kode ini mengambil daftar pemberitahuan dari Netskope. Jika konektor berjalan dalam mode pengujian, hanya pemberitahuan terakhir dalam daftar yang dipilih (baris 79–80).

Logika Tambahan

Kemudian, Konektor melakukan iterasi melalui pemberitahuan yang diambil dan membuat pemberitahuan dari setiap pemberitahuan menggunakan fungsi build_alert_info yang ditentukan sebelumnya. Tindakan ini menambahkan setiap pemberitahuan ke daftar all_alerts, yang diinisialisasi sebelumnya. Bagian berikutnya dari logika konektor menangani overflow.
Overflow adalah mekanisme ambang batas yang mencegah terlalu banyak pemberitahuan yang diproses dalam waktu singkat, terutama saat pemberitahuan berbagi lingkungan, produk, dan generator aturan yang sama. Meskipun tidak wajib, sebaiknya terapkan logika overflow sebagai praktik terbaik untuk mencegah penurunan performa.

Tinjau perincian logika overflow per baris skrip pada Gambar 4:

• Di baris 104–105, jika alert tidak diklasifikasikan sebagai overflow, alert tersebut akan ditambahkan ke daftar pemberitahuan yang akan diproses.



Gambar 4: Mekanisme overflow.

Mengakhiri eksekusi konektor

Jika konektor tidak berjalan dalam mode pengujian, stempel waktu harus diperbarui untuk mencerminkan pemberitahuan terakhir yang diambil. Hal ini memastikan bahwa pemberitahuan yang sama tidak dimasukkan kembali selama siklus eksekusi berikutnya. Daftar all_alerts diurutkan berdasarkan stempel waktu sehingga meskipun pemberitahuan meluap, pemberitahuan tersebut tetap berkontribusi dalam menentukan stempel waktu terbaru.

Tinjau perincian logika eksekusi konektor per baris skrip pada Gambar 5:

• Di baris 126, daftar pemberitahuan yang tidak meluap dikirimkan ke aplikasi, tempat pemberitahuan tersebut dibuat dan ditampilkan di GUI.
• Di baris 128–131, mereka menentukan apakah konektor berjalan dalam mode pengujian. Argumen sistem yang diteruskan oleh aplikasi, seperti saat mengklik Jalankan Konektor Sekali di tab Pengujian, digunakan untuk membuat penentuan ini.
  

  

  Gambar 5: Mengakhiri eksekusi konektor

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.