Mengembangkan transformer kustom

Didukung di:

Google secops SOAR

Catatan: Fitur ini tercakup dalam Persyaratan Penawaran Pra-GA dari Persyaratan Khusus Layanan Google Security Operations. Fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat panduan Layanan Dukungan Teknis Google SecOps dan Persyaratan Khusus Layanan Google SecOps.
Jika fitur ini tidak terlihat di lingkungan Anda, lihat Mengelola fitur pratinjau atau hubungi administrator sistem.

Anda dapat membuat fungsi transformasi dan operator logis berbasis Python kustom langsung di dalam IDE dan menggunakannya di playbook untuk kasus penggunaan yang kompleks dan serbaguna.

Paket Ekstensi

Paket ekstensi adalah jenis integrasi khusus yang dirancang untuk bertindak sebagai penampung fungsi transformasi kustom dan operator logis. Tidak seperti integrasi standar, paket ekstensi tidak memerlukan konfigurasi instance dan dapat dibuat langsung dari IDE.

Praktik terbaik untuk paket ekstensi

• Konsolidasi: Buat satu paket ekstensi utama dan tambahkan beberapa fungsi transformasi atau operator logis ke dalamnya.
• Pemisahan: Buat paket ekstensi baru jika Anda memerlukan kumpulan library Python (dependensi) yang berbeda yang mungkin bertentangan dengan paket utama.

Penting: Membuat paket ekstensi di IDE memerlukan izin Semua lingkungan.

Membuat Paket Ekstensi

Untuk membuat paket ekstensi baru, ikuti langkah-langkah berikut:

1. Buka Respons > IDE.
2. Klik add Buat Item Baru.
3. Pilih Paket Ekstensi dari menu drop-down.
4. Berikan Nama unik untuk Paket Ekstensi.
Catatan: Nama tidak dapat diubah setelah dibuat.
5. Klik Simpan.

Mengupload dependensi

Seperti integrasi standar, paket ekstensi berjalan di lingkungan virtual tempat Anda dapat mengelola library Python.

Untuk mengelola library, ikuti langkah-langkah berikut:

1. Buka setelan Paket Ekstensi di IDE.
2. Tambahkan library Python yang diperlukan dari PyPi atau upload dari komputer Anda.

Dependensi ini tersedia untuk semua transformer dan operator logis yang terdapat dalam paket ekstensi tertentu ini.

Impor dan Ekspor

Anda dapat mengimpor dan mengekspor paket ekstensi secara manual langsung dalam antarmuka IDE.

Catatan: Impor dan ekspor mungkin tidak tersedia untuk pelanggan yang belum menyelesaikan migrasi tahap 2. Untuk mengetahui informasi selengkapnya, lihat Ringkasan migrasi SOAR.

Transformer Kustom

Transformer Kustom adalah fungsi Python yang ditentukan pengguna yang memperluas fungsi bawaan di Builder Ekspresi. Anda dapat membuatnya langsung di dalam IDE untuk mengekstrak dan memanipulasi data, dan dapat digunakan bersama fungsi bawaan yang ada.

Membuat transformer kustom

Untuk menentukan transformer kustom baru, ikuti langkah-langkah berikut:

1. Di IDE, temukan paket ekstensi target Anda.
2. Pilih paket ekstensi target untuk menambahkan item baru di bagian paket.
3. Pilih Fungsi Transformasi Kustom.
4. Beri nama.
Catatan: Nama tidak dapat diubah setelah dibuat.
5. Opsional: Tambahkan deskripsi. Deskripsi ini ditampilkan saat Anda mengarahkan kursor ke transformer kustom di Builder Ekspresi.
6. Tentukan logika skrip menggunakan Python. Anda dapat menggunakan template default yang disediakan sebagai titik awal.
   • Skrip harus menyertakan fungsi main seperti yang ditunjukkan dalam template yang telah ditentukan.
   • Skrip harus menampilkan hasil ke builder ekspresi menggunakan fungsi SDK end.
   • Input transformer kustom dapat berupa berbagai jenis (misalnya, string atau daftar). Pastikan Anda mengonversinya ke jenis yang diharapkan dalam fungsi main.
   • Anda hanya dapat menggunakan sebagian metode SDK dalam IDE untuk transformer:
     • transformer.extract_param("ParamName"): Untuk mengambil nilai input.
     • transformer.LOGGER: Untuk menulis log untuk proses debug.
     • transformer.end(result): Untuk menampilkan nilai yang diubah.
7. Buat parameter:
   • Setiap fungsi transformer kustom menyertakan parameter Input default. Parameter ini mewakili data input, yang merupakan placeholder yang diterapkan fungsi. Anda tidak dapat menghapus parameter ini.
   • Selain itu, Anda dapat menambahkan parameter opsional yang akan digunakan dalam fungsi Anda.
8. Dokumentasi (Opsional): Tentukan dokumentasi dalam produk untuk Builder Ekspresi:
   • Input yang Diharapkan: Jelaskan jenis data yang diharapkan akan diterima fungsi untuk transformer ini (misalnya, "String" atau "Daftar string").
   • Output yang Diharapkan: Jelaskan jenis data yang diharapkan akan ditampilkan fungsi untuk transformer ini (misalnya, "boolean").
   • Contoh Penggunaan: Berikan contoh cara memanggil fungsi (misalnya, if_empty("new_value")).

Anda dapat menguji logika fungsi transformasi kustom langsung di dalam IDE sebelum menggunakannya di playbook. Hal ini memungkinkan Anda memverifikasi bahwa skrip Python Anda menangani berbagai jenis dan parameter input dengan benar serta menampilkan hasil yang diharapkan.

Waktu habis

• Waktu Habis Default: 1 menit.
• Waktu Habis Maksimum: 3 menit.

Catatan: Karena platform menunggu fungsi selesai, Anda harus meminimalkan waktu eksekusi. Fokus pada transformasi data langsung dan hindari pemrosesan berat atau membuat kueri sumber eksternal.

Menggunakan transformer kustom di Builder Ekspresi

Setelah disimpan, transformer kustom akan muncul dalam daftar fungsi Builder Ekspresi bersama fungsi bawaan. Transformer kustom diidentifikasi dengan format: ExtensionPackName.TransformerName. Mengarahkan kursor ke fungsi akan menampilkan dokumentasi yang dibuat dari deskripsi parameter Anda.

Dukungan untuk semua placeholder (JSON dan non-JSON)

Builder Ekspresi mendukung setiap placeholder yang ditampilkan di Desainer Playbook, termasuk hasil non-JSON.

Untuk placeholder non-JSON:

• Anda dapat memasukkan data contoh secara manual ke Builder Ekspresi untuk menguji logika terhadap berbagai jenis input: string, daftar (nilai yang dipisahkan koma), dan JSON.
• Pengujian dengan jenis input tidak menjamin placeholder akan menampilkan jenis tertentu tersebut saat runtime.
• Sebagian besar placeholder di-resolve sebagai string, kecuali untuk jenis tertentu yang di-resolve sebagai string atau daftar berdasarkan jumlahnya (misalnya, entity.identifier). Untuk placeholder ini, sebaiknya selalu perlakukan input sebagai daftar.

Catatan: Data contoh bersifat sementara dan tidak akan disimpan setelah Anda menutup Builder Ekspresi atau menyimpan ekspresi. Anda harus memasukkan kembali data contoh jika membuka builder lagi.

Penanganan Error

Jika fungsi transformasi kustom mengalami error selama eksekusi, tindakan playbook yang menggunakan transformer tersebut akan gagal. Pesan error tertentu yang dihasilkan oleh skrip Python ditampilkan di layar dalam tampilan eksekusi playbook, sehingga Anda dapat memecahkan masalah logika secara langsung.

Operator Logis Kustom

Operator Logis Kustom memungkinkan Anda menentukan logika boolean sendiri untuk membandingkan nilai.

Membuat operator logis kustom

Untuk menentukan operator logis baru, ikuti langkah-langkah berikut:

1. Di IDE, temukan Paket Ekstensi target Anda.
2. Pilih Operator Logis Kustom.
3. Beri nama.
Catatan: Nama tidak dapat diubah setelah dibuat.
4. Opsional: Tambahkan deskripsi untuk menu operator logis di Desainer Playbook.
5. Tentukan logika skrip menggunakan Python. Anda dapat menggunakan template yang telah ditentukan yang disediakan sebagai titik awal.
   • Skrip harus menyertakan fungsi main.
   • Skrip harus menampilkan hasil boolean ke kondisi dengan menggunakan fungsi end SDK.
   • Anda hanya dapat menggunakan sebagian metode SDK dalam IDE untuk operator logis:
   • logical_operator.extract_param("ParamName"): Untuk mengambil nilai input.
   • logical_operator.LOGGER: Untuk menulis log untuk proses debug.
   • logical_operator.end(result): Hasilnya adalah nilai boolean (true atau false).

Anda dapat menguji logika operator logis kustom langsung di dalam IDE. Hal ini memungkinkan Anda memasukkan nilai pengujian untuk argumen dan memverifikasi bahwa fungsi menampilkan hasil boolean (Benar atau Salah) yang benar berdasarkan kondisi yang Anda tentukan.

Parameter

Operator logis kustom menerima dua parameter: Sisi Kiri (wajib dan tidak dapat diedit) dan Sisi Kanan (opsional; dapat dinonaktifkan oleh pengguna).

• Contoh 1: if [left side] not in [right side].
• Contoh 2: if [left side] is greater than 80 (tidak ada sisi kanan).

Waktu habis

• Waktu Habis Default: 1 menit.
• Waktu Habis Maksimum: 3 menit.

Catatan: Karena platform menunggu fungsi selesai, Anda harus meminimalkan waktu eksekusi. Praktik terbaiknya adalah berfokus pada transformasi data langsung dan menghindari membuat kueri sumber eksternal atau melakukan pemrosesan berat.

Menggunakan di playbook

Operator logis kustom muncul di menu operator dalam Kondisi Playbook, Kondisi Tindakan Sebelumnya, dan Pemilihan Entity.

Operator logis kustom dapat dipilih bersama operator standar (misalnya, "Sama Dengan" atau "Berisi").

Penanganan Error

Jika fungsi operator logis kustom mengalami error selama eksekusi, kondisi atau langkah playbook yang menggunakan operator tersebut akan gagal. Pesan error yang ditampilkan oleh skrip Python ditampilkan dalam tampilan eksekusi playbook untuk membantu pemecahan masalah.

Batasan

• Fungsi transformasi kustom dan operator logis tidak didukung di Pemicu atau Webhook.

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