Membangun integrasi kustom

Didukung di:

Google SecOps SOAR

Dokumen ini menjelaskan alur kerja untuk membangun integrasi kustom untuk Google SecOps. Praktik terbaik saat ini adalah mengembangkan integrasi secara lokal menggunakan IDE pilihan Anda dan mengelolanya melalui GitHub menggunakan alur kerja GitOps modern. Untuk lingkungan lama atau prototipe cepat, Anda juga dapat membangun integrasi langsung di dalam IDE SOAR bawaan.

Catatan: Untuk mengetahui framework pengembangan standar, panduan uji mutu, dan praktik terbaik untuk membangun dan mengirimkan integrasi kustom, lihat Panduan integrasi kustom.

Alur kerja IDE lokal & GitHub (direkomendasikan)

Mengembangkan integrasi secara lokal dan mengelolanya melalui GitHub adalah alur kerja yang direkomendasikan. Pendekatan ini selaras dengan praktik GitOps modern, sehingga memungkinkan kontrol versi, kolaborasi, dan pengelolaan dependensi otomatis yang lebih baik.

Untuk langkah-langkah teknis mendetail, panduan pemasangan, dan perintah modern menggunakan alat Marketplace CLI dan pengelola paket uv, lihat Repositori GitHub Chronicle Content Hub resmi.

Ringkasan alur kerja konseptual

Untuk mengembangkan integrasi kustom secara lokal, sebaiknya ikuti siklus proses GitOps ini. Untuk mengetahui sintaksis yang tepat dan terbaru dari perintah ini, lihat dokumentasi MP CLI resmi di GitHub.

1. Fork dan clone: Buat clone repositori content-hub resmi ke mesin pengembangan lokal Anda.
2. Menginstal alat: Instal alat mp CLI dan pengelola paket Python uv.
3. Melakukan autentikasi: Login ke lingkungan Google SecOps Anda melalui MP CLI menggunakan URL instance dan kunci API Anda.
4. Kembangkan secara lokal: Gunakan IDE pilihan Anda (seperti VS Code atau PyCharm) untuk menulis kode integrasi, dengan memanfaatkan alat proses debug dan pengujian lokal.
5. Mengelola dependensi: Gunakan uv untuk mendeklarasikan dan mengelola dependensi (seperti TIPCommon) dalam file pyproject.toml lokal Anda.
6. Sinkronkan: Gunakan perintah mp pull dan mp push untuk menyinkronkan kode lokal Anda dengan instance Google SecOps untuk pengujian dan deployment.

Alternatif: Membuat integrasi kustom di IDE bawaan

Jika Anda mengelola integrasi lama, menguji skrip dengan cepat, atau bekerja di lingkungan dengan pengembangan lokal yang dibatasi, Anda dapat menggunakan IDE bawaan.

Kasus penggunaan: Membangun integrasi Armis kustom

Untuk membuat integrasi kustom di IDE, ikuti langkah-langkah berikut:

1. Di menu utama, buka Response > IDE.
2. Klik Create New Item, lalu pilih Integration.
3. Masukkan nama, lalu klik Buat.

Integrasi kini tercantum dengan opsi settings Settings, yang menunjukkan bahwa integrasi tersebut adalah integrasi kustom.

Klik settings Settings untuk menampilkan setelan integrasi tempat Anda dapat menentukan ikon, deskripsi, dependensi Python, dan parameter integrasi.

Catatan: Dependensi skrip adalah library Python yang diperlukan oleh integrasi kustom Anda. Dependensi dapat diupload sebagai file .WHL, .TAR, .GZ, atau .PY. Setiap integrasi berjalan di lingkungan virtualnya sendiri, sehingga Anda dapat menggunakan versi library tertentu, terlepas dari apa yang diinstal pada sistem yang mendasarinya.

Jika Anda menggunakan file .WHL kustom atau eksklusif (seperti TIPCommon) yang memerlukan sub-dependensi bertingkat, Anda harus mengupload file wheel satu per satu secara manual untuk seluruh hierarki dependensi sebelum menyimpan. Kegagalan dalam menyelesaikan dependensi bertingkat akan menyebabkan kegagalan errorCode: 2000 umum. Untuk pelacakan dependensi lanjutan, pertimbangkan untuk menggunakan alur kerja IDE Lokal & GitHub.

Membuat pengelola kustom

Pengelola adalah wrapper untuk API alat pihak ketiga. Meskipun tidak wajib, kami merekomendasikannya untuk integrasi yang berinteraksi dengan alat eksternal. Pengelola tidak boleh mengimpor dari SDK. Setelah dibuat, impor ke konektor, tindakan, dan tugas.

Untuk membuat pengelola kustom, ikuti langkah-langkah berikut:

1. Di IDE, klik Create New Item, lalu pilih Manager.
2. Pilih integrasi Armis dan masukkan nama pengelola.
   
3. Edit dan jalankan skrip berikut:

import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) Respons yang akan divalidasi
       :param error_msg: (str) Pesan error yang akan ditampilkan
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

Catatan: Pengelola tidak diperlukan untuk tindakan dasar. Namun, sebaiknya buat satu skema saat mengelompokkan tindakan kecil untuk penguraian dan transformasi data.

Parameter, konfigurasi Google SecOps Content Hub, dan tindakan Ping

Parameter yang ditentukan dalam setelan integrasi akan muncul di konfigurasi Google SecOps Content Hub. Parameter tersebut mencakup:

• API Root: URL dasar untuk layanan yang Anda hubungkan.
• Rahasia API: Kunci rahasia yang digunakan untuk mengautentikasi aplikasi Anda dengan layanan.
• Kotak centang Verify SSL: Jika diaktifkan, akan memverifikasi bahwa sertifikat SSL untuk koneksi ke server Armis valid.
• Kotak centang Run Remotely: Setelan yang menentukan apakah kode atau tugas akan dijalankan di server jarak jauh, bukan secara lokal. Jika opsi ini diaktifkan, sistem akan mengirimkan petunjuk dan data yang diperlukan ke server khusus untuk diproses.

Untuk memperbarui parameter, ikuti langkah-langkah berikut:

1. Masukkan kredensial yang benar.
2. Klik Save > Test.

Catatan: Selalu klik Save setelah memperbarui kredensial. Semua integrasi pihak ketiga harus menerapkan tindakan Ping. Tombol Test menjalankan tindakan ini untuk memvalidasi konektivitas.

Jika tindakan Ping tidak ada, tombol Test akan gagal dan menampilkan tanda X merah.

Mengimplementasikan tindakan Ping

Logika tindakan Ping bertindak seperti autentikasi yang berhasil.

Untuk menerapkan tindakan Ping, lakukan hal berikut:

1. Di IDE, buat Action baru dalam integrasi Armis bernama Ping.
2. Gunakan metode ArmisManager auth untuk memverifikasi autentikasi.

Mengaktifkan integrasi

Untuk mengaktifkan integrasi, ikuti langkah-langkah berikut:

1. Di Response > IDE, klik tombol Enable/Disable ke posisi ON.
2. Klik Simpan. Tombol hijau mengonfirmasi keberhasilan. Kredensial dari Hub Konten diteruskan ke ArmisManager. Jika auth selesai tanpa error, tombol Test akan menampilkan tanda centang hijau.

Gunakan metode extract_configuration_param untuk mengimpor parameter dari konfigurasi integrasi. Atau, gunakan extract_action_param untuk menentukan parameter dalam tindakan itu sendiri. Namun, tindakan Ping harus selalu menggunakan parameter konfigurasi, karena parameter tersebut diuji oleh Content Hub.

Melihat integrasi kustom

Buka Hub Konten dan telusuri integrasi kustom yang Anda buat. Jika Anda tidak membuat image selama konfigurasi awal, image kustom default akan ditetapkan ke image tersebut. Perhatikan bahwa update Content Hub tidak mengganti atau menghapus integrasi kustom apa pun.

Mengekspor dan mengimpor di IDE

Lakukan salah satu tindakan berikut:

• Untuk mengimpor integrasi, lakukan hal berikut:
1. Upload file ZIP dengan struktur folder yang benar; integrasi akan muncul di IDE dan Content Hub.
2. Klik Import. Integrasi ini muncul di IDE dan Hub Konten.
3. Sistem akan membuat file ZIP yang berisi definisi, skrip, dan konfigurasi. Folder Pengelola tidak disertakan secara otomatis.
• Untuk mengekspor integrasi, lakukan hal berikut:
• Klik Ekspor untuk mendownload paket.

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