Membuat integrasi kustom

Didukung di:

Google secops SOAR

Dokumen ini menjelaskan cara membuat integrasi kustom di dalam Integrated Development Environment (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 dalam playbook, tindakan manual, dan agen jarak jauh. Kemampuan impor dan ekspor juga didukung, mirip dengan item IDE lainnya.

Catatan: Untuk mengetahui framework pengembangan standar, panduan jaminan 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: Membuat integrasi Armis kustom

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

1. Di menu utama, buka Respons > IDE.
2. Klik Buat Item Baru , lalu pilih Integrasi.
3. Masukkan nama, lalu klik Buat.

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

Klik settings Setelan 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 .WHL, .TAR, .GZ, atau .PY file. 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 versi library permintaan yang berbeda, download dari sumber tepercaya seperti PyPI atau GitHub dan tambahkan sebagai dependensi skrip.
Untuk dependensi yang memerlukan roda biner yang telah dikompilasi sebelumnya (seperti paket dengan ekstensi C), platform SOAR menggunakan cpython standar yang dibuat berdasarkan manylinux_2_17_x86_64 arsitektur. Saat memilih file .WHL, pastikan file tersebut kompatibel dengan tag ini.
Jika library tidak diinstal di lingkungan virtual, integrasi akan menggunakan kembali versi yang diinstal sistem.

Jika Anda menggunakan file .WHL kustom atau eksklusif (seperti TIPCommon) yang memerlukan sub-dependensi bertingkat, Anda harus mengupload file roda individual secara manual untuk seluruh pohon dependensi (misalnya: anyio, certifi, httpx, idna, atau sniffio) sebelum menyimpan. Kegagalan menyelesaikan dependensi bertingkat akan menyebabkan kegagalan generik errorCode: 2000. Untuk mengetahui daftar lengkap library platform yang diperlukan, lihat Panduan Komunitas tentang Mengambil TIPCommon.

Jika paket dependensi tidak memiliki file roda (.WHL) yang telah dikompilasi sebelumnya yang tersedia 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). Pemecah dependensi platform, uv, mendukung penentuan URL sumber ini dalam tabel dalam file pyproject.toml Anda.[tool.uv.sources] 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 seperti TIPCommon, Google merekomendasikan untuk sepenuhnya melewati upload IDE manual 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 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 Anda 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 instance SOAR lama dan format kunci API 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 TIPCommon atau Dependensi Kompleks ke Integrasi

Jika Anda memiliki integrasi yang dibuat di IDE yang memerlukan TIPCommon atau library berlapis 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 ditarik:

   cd {INTEGRATION_NAME}

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

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

5. Kirim integrasi yang dikompilasi sepenuhnya beserta pohon dependensi yang baru dilacak 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 Uji/Putar untuk men-debug eksekusi. Jika skrip dikompilasi dengan bersih tanpa menampilkan ModuleNotFoundError, dependensi bertingkat Anda akan diselesaikan dengan benar.

Membuat pengelola kustom

Pengelola adalah wrapper untuk API alat pihak ketiga. Meskipun tidak wajib, sebaiknya gunakan pengelola 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 Buat Item Baru dan pilih Pengelola.
2. Pilih integrasi Armis , lalu 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) The response to validate
       :param error_msg: (str) The error message to display
       """
       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 pengelola saat mengelompokkan tindakan kecil untuk penguraian dan transformasi data.

Parameter, konfigurasi Hub Konten Google SecOps, 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.
• Rahasia 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 Jalankan dari Jarak Jauh: 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.

Mengimplementasikan tindakan Ping

Logika tindakan Ping berfungsi seperti autentikasi yang berhasil.

Untuk mengimplementasikan tindakan Ping, lakukan hal berikut:

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

Mengaktifkan integrasi

Untuk mengaktifkan integrasi, ikuti langkah-langkah berikut:

1. Di Respons > IDE, klik tombol Aktifkan/Nonaktifkan ke posisi AKTIF.
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 gambar selama konfigurasi awal, gambar kustom default akan ditetapkan untuk integrasi tersebut. Perhatikan bahwa update Hub Konten 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 Hub Konten.
2. Klik Import. Integrasi akan 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.