Membangun integrasi kustom

Didukung di:

Google secops SOAR

Dokumen ini menjelaskan cara membuat integrasi kustom di dalam Lingkungan Pengembangan Terintegrasi (IDE) menggunakan struktur yang sama dengan integrasi komersial. Anda dapat menemukan dan mengonfigurasi integrasi kustom di Hub Konten untuk berbagai lingkungan. Kemudian, Anda dapat menggunakannya di playbook, tindakan manual, dan agen jarak jauh. Kemampuan impor dan ekspor juga didukung, serupa dengan item IDE lainnya.

Catatan: Untuk mengetahui framework pengembangan standar, pedoman penjaminan kualitas, dan praktik terbaik untuk membangun dan mengirimkan integrasi kustom, lihat Praktik Terbaik.

Membuat integrasi kustom di IDE

Anda dapat membuat integrasi kustom untuk produk Armis dan membuat pengelola beserta tindakan Ping. Pengetahuan tentang Python dan pemrograman berorientasi objek diasumsikan untuk prosedur ini.

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 Buat Item Baru, lalu pilih Integrasi.
3. Masukkan nama, lalu klik Buat.

Integrasi kini dicantumkan dengan opsi setelan Setelan, 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. Misalnya, untuk menggunakan library permintaan versi lain, download dari sumber tepercaya seperti PyPI atau GitHub dan tambahkan sebagai dependensi skrip.
Untuk dependensi yang memerlukan wheel biner yang telah dikompilasi sebelumnya (seperti paket dengan ekstensi C), platform SOAR menggunakan cpython standar yang dibangun berdasarkan arsitektur manylinux_2_17_x86_64. Saat memilih file .WHL, pastikan file tersebut kompatibel dengan tag ini.
Jika library tidak diinstal di lingkungan virtual, integrasi akan melakukan fallback ke versi yang diinstal sistem.

Jika paket dependensi tidak memiliki file wheel (.WHL) yang telah dikompilasi sebelumnya untuk arsitektur manylinux_2_17_x86_64, atau jika Anda memerlukan versi kode sumber tertentu, Anda dapat memberikan URL langsung ke kode sumber (misalnya, file .tar.gz). Resolver dependensi platform, uv, mendukung penentuan URL sumber ini dalam tabel [tool.uv.sources] dalam file pyproject.toml Anda. Contoh:

[project]
# ... other project fields ...

[tool.uv.sources]
# The key (e.g., compressed-rtf) must match the dependency name
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

Untuk mengetahui detail selengkapnya tentang cara menentukan berbagai jenis dependensi menggunakan uv, lihat dokumentasi uv tentang Mengelola dependensi.

Membuat pengelola kustom

Pengelola adalah wrapper untuk API alat pihak ketiga. Meskipun tidak wajib, sebaiknya gunakan 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 saat mengelompokkan tindakan kecil untuk parsing dan transformasi data.

Parameter, konfigurasi Google SecOps Content Hub, dan tindakan Ping

Parameter yang ditentukan dalam setelan integrasi muncul dalam konfigurasi Hub Konten Google SecOps. Parameter ini meliputi:

• Root API: URL dasar untuk layanan yang Anda hubungkan.
• Secret API: Kunci rahasia yang digunakan untuk mengautentikasi aplikasi Anda dengan layanan.
• Kotak centang Verifikasi 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 dieksekusi 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 Simpan > Uji.

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

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

Menerapkan tindakan Ping

Logika tindakan Ping berfungsi seperti autentikasi yang berhasil.

Untuk menerapkan tindakan Ping, lakukan hal berikut:

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

Aktifkan 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 Uji 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 Hub Konten.

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 VM tersebut. Perhatikan bahwa pembaruan Hub Konten tidak menggantikan 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 Hub Konten.
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.