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 membuat dan mengirimkan integrasi kustom, lihat Panduan integrasi kustom.

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 ini 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 Anda menggunakan file .WHL kustom atau berpemilik (seperti TIPCommon) yang memerlukan sub-dependensi bertingkat, Anda harus mengupload file wheel satu per satu untuk seluruh hierarki dependensi (misalnya: anyio, certifi, httpx, idna, atau sniffio) sebelum menyimpan. Jika gagal menyelesaikan dependensi bertingkat, akan terjadi kegagalan errorCode: 2000 generik. Untuk mengetahui daftar lengkap library platform yang diperlukan, lihat Panduan Komunitas tentang Mengambil TIPCommon.

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]
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.

Alur kerja yang direkomendasikan: Pengelolaan dependensi lanjutan menggunakan mp CLI

Untuk integrasi yang memerlukan library eksternal yang kompleks atau berlapis-lapis seperti TIPCommon, Google merekomendasikan untuk melewati upload IDE manual sepenuhnya dan mengembangkannya secara lokal menggunakan alat Marketplace CLI (mp). Alat ini secara otomatis melacak dan mengemas dependensi bertingkat menggunakan pengelola paket uv.

Prasyarat

• Python 3.11 atau yang lebih baru diinstal di mesin pengembangan lokal Anda.
• Pengelola paket Python uv telah diinstal (lihat panduan penginstalan uv).

Penyiapan Awal

1. Lakukan fork dan clone repositori Hub Konten resmi ke lingkungan lokal Anda.
2. Instal alat mp menggunakan uv:

   uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp

3. Login ke lingkungan Google SecOps menggunakan URL root instance dan kunci API lama Anda:

   mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}

   Catatan: Alat CLI memerlukan URL dan format kunci API instance SOAR lama Anda untuk autentikasi.
4. Konfigurasi jalur repositori root lokal Anda:

   mp config --root-path /path/to/cloned/content-hub

5. Buat subdirektori kustom untuk integrasi eksklusif Anda dalam tata letak repositori di: content-hub/content/response_integrations/custom/

Menambahkan Dependensi Umum atau Kompleks TIP ke Integrasi

Jika Anda memiliki integrasi yang dibuat di IDE yang memerlukan TIPCommon atau library multi-layer lainnya, gunakan alur kerja lokal berikut untuk mengelola dependensinya dengan aman:

1. Buka direktori integrasi kustom Anda di dalam repositori yang di-clone:

   cd content-hub/content/response_integrations/custom/

2. Tarik struktur integrasi yang ada dari instance Google SecOps Anda:

   mp pull --type integration --name "{INTEGRATION_NAME}"

3. Ubah direktori ke folder integrasi yang baru saja ditarik:

   cd {INTEGRATION_NAME}

4. Gunakan uv untuk menyuntikkan paket file wheel TIPCommon yang diperlukan. Tindakan ini akan otomatis melacak dan mendownload wheel sub-dependensi bertingkat ke konfigurasi paket lingkungan lokal Anda:

   uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl

5. Dorong integrasi yang dikompilasi sepenuhnya beserta hierarki dependensi yang baru dilacaknya kembali ke instance Google SecOps Anda:

   mp push --type integration --name "{INTEGRATION_NAME}"

Memverifikasi penginstalan

Untuk mengonfirmasi bahwa dependensi Anda berhasil dikemas tanpa mengalami loop errorCode: 2000, lakukan hal berikut:

• Buka integrasi kustom Anda di dalam IDE.
• Tambahkan baris pengujian untuk mengimpor modul dari paket, seperti: from TIPCommon.extraction import extract_action_param
• Klik tombol Test/Play untuk men-debug eksekusi. Jika skrip dikompilasi dengan bersih tanpa memunculkan ModuleNotFoundError, dependensi bertingkat Anda akan diselesaikan dengan benar.

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 mencakup:

• 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 bertindak 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.