Halaman ini diterjemahkan oleh Cloud Translation API.

Pedoman kontribusi komunitas integrasi respons

Didukung di:

Google secops SOAR

Dokumen ini menguraikan pedoman untuk mengirimkan Integrasi Respons ke Google SecOps melalui kontribusi komunitas. Semua integrasi yang dikirimkan akan menjalani proses seleksi oleh tim Google SecOps resmi, dengan berfokus pada persyaratan yang ditandai dalam dokumen ini.

Metadata integrasi respons

Nama

Nama harus sesuai dengan nama produk yang akan diintegrasikan dengan integrasi dan tidak boleh berisi karakter khusus.

Nama Tampilan harus ditulis dengan spasi; misalnya, Vertex AI, bukan VertexAI.

ID Integrasi

ID Integrasi adalah ID unik dari integrasi. Setelah integrasi dibuat, nilai ini tidak dapat diubah. ID harus memiliki nilai yang sama dengan Name, tetapi dengan spasi dihapus.

ID tersedia di sebagian besar tempat di seluruh platform.

Deskripsi

Deskripsi harus memberikan ringkasan tingkat tinggi tentang produk yang integrasinya dibuat dan tidak boleh melebihi 500 karakter. Harus berisi informasi berikut:

This integration is owned by the "{vendor name}". Support Contact: {email}.

Hindari menyertakan URL dalam deskripsi.

Logo

Setiap integrasi harus dilengkapi dengan ikon SVG. Ikon ini harus beradaptasi dengan tema di dalam platform. Ikon hanya boleh mewarisi tema dari platform.

Anda harus memvalidasi logo di halaman berikut:

Respons > Penyiapan Integrasi
Respons > Playbook > Desainer Playbook
Kasus > Peringatan > Tampilan Buku Pedoman Peringatan

Berikut adalah contoh logo SVG, yang didesain agar sesuai dengan panduan gaya kami:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>

Pastikan untuk mengenkode SVG sebelum menambahkannya ke file definisi integrasi, seperti yang dapat ditemukan di integrasi lain di marketplace.

Link dokumentasi

Sebagai bagian dari integrasi, Anda dapat menambahkan link yang akan mengarahkan pengguna ke dokumentasi. Dokumentasi ini diharapkan dihosting di sisi Anda.

Pengguna dapat mengakses link dokumentasi dari bagian Parameter pada dialog Konfigurasi Instance.

Parameter konfigurasi

Semua integrasi harus berisi parameter konfigurasi (parameter Root API + Auth), kecuali jika API yang mendasarinya tidak memerlukan autentikasi apa pun dan Root API dapat dikodekan secara permanen. Untuk semua integrasi yang memerlukan autentikasi, harus ada parameter Verify SSL.

Semua parameter harus memiliki deskripsi. Deskripsi ini akan membantu pengguna mengonfigurasi integrasi dari dalam platform. Hindari menempatkan URL dalam deskripsi parameter.

Tindakan ping

Tindakan ping adalah tindakan khusus yang digunakan oleh platform untuk memvalidasi konektivitas API. Tindakan ini wajib dilakukan meskipun integrasi Anda tidak memiliki tindakan lain. Setiap kali pengguna menekan tombol Uji di dalam konfigurasi integrasi, tombol tersebut harus menampilkan status konektivitas yang akurat.

Catatan rilis

Struktur umum catatan rilis harus mengikuti format berikut:

{integration item} - {update}

Contoh: Get Case Details - Added ability to fetch information about affected IOCs

Bergantung pada situasinya, ada catatan rilis unik untuk skenario tertentu:

Jika ini adalah integrasi baru: New Integration Added - {integration name}
Jika tindakan baru ditambahkan: New Action Added - {action name}
Jika konektor baru ditambahkan: New Connector Added - {connector name}
Jika pekerjaan baru ditambahkan: New Job Added - {job name}
Jika widget bawaan ditambahkan ke tindakan: {action name} - Added Predefined Widget.
Jika widget standar diperbarui: {action name} - Updated Predefined Widget.
Untuk perubahan yang memengaruhi semua item integrasi: Integration - {Update}
Untuk perubahan yang memengaruhi semua tindakan: Integration's Actions - {Update}
Untuk perubahan yang memengaruhi semua konektor: Integration's Connectors - {Update}
Untuk perubahan yang memengaruhi semua tugas: Integration's Jobs - {Update}

Jika rilis berisi perubahan regresif, maka di catatan rilis, Anda harus menentukan REGRESSIVE!. Misalnya, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Catatan rilis tersedia di panel samping Detail Integrasi yang ditampilkan saat Anda mengklik tombol Detail dalam integrasi.

Pembuatan Versi

Setiap update integrasi harus diikuti dengan update +1 pada versi integrasi. Versi harus direpresentasikan sebagai bilangan bulat. Versi kecil seperti 11.1.3 atau 11.1 tidak diizinkan.

Tag

Secara opsional, Anda dapat menambahkan tag ke integrasi. Hindari pembuatan jenis tag baru; gunakan tag yang sudah ada di dalam platform. Jika Anda tidak melihat tag yang sesuai, konsultasikan dengan tim seleksi.

Catatan umum

Uji setiap konten integrasi sebelum pengiriman.
Tinjau semua konten integrasi untuk mengetahui potensi kerentanan dan dependensi yang rentan.
Selalu gunakan Python versi terbaru yang didukung selama pengembangan (Python 3.11).

Tindakan

Nama

Nama tindakan harus mengarah ke aktivitas yang sedang dilakukan; misalnya, Get Case Details, List Entity Events, atau Execute Search.

Jika tindakan dirancang untuk bekerja terutama dengan entitas, sebaiknya letakkan Entity dalam nama; misalnya, Enrich Entities.

Nama tindakan harus disampaikan dalam 2-3 kata.

Deskripsi

Deskripsi tindakan harus menjelaskan kepada pengguna apa yang akan menjadi hasil eksekusi tindakan.

Jika tindakan berfungsi dengan entitas, Anda harus menambahkan informasi tentang jenis entitas yang didukung. Contoh:

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Jika tindakan berfungsi dalam mode Async, Anda harus memberikan catatan berikut dalam deskripsi:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Cobalah untuk membatasi deskripsi hingga 500 karakter.

Parameter tindakan

Parameter konfigurasi tindakan harus memiliki nama yang intuitif. Hindari penggunaan karakter khusus dan coba batasi nama parameter tindakan menjadi 2-4 kata.

Deskripsi parameter harus menjelaskan kepada pengguna dampak parameter tersebut terhadap eksekusi tindakan. Jika parameter mendukung sejumlah nilai yang didukung yang telah ditentukan sebelumnya, maka di dalam deskripsi berikan bagian berikut: Possible Values: {value 1}, {value 2}

Output tindakan (hasil skrip)

Hasil skrip harus merepresentasikan hasil sederhana dari tindakan. Dalam sebagian besar kasus, kolom ini hanya akan mengarah ke variabel yang disebut is_success, yang dapat mengambil nilai true atau false.

Secara umum, jika tindakan selesai dieksekusi dan melakukan operasi, is_success harus true.

Output tindakan (hasil JSON)

Hasil JSON adalah output terpenting dari tindakan. Semua data yang tersedia dalam hasil JSON akan dapat diakses selama eksekusi playbook. Pastikan objek JSON yang valid dikirim ke output.

Hasil JSON memiliki batas ukuran 15 MB.

Saat membuat hasil JSON, pastikan tidak ada kunci yang akan bersifat unik selama eksekusi. Misalnya, objek JSON berikut merepresentasikan struktur yang buruk karena tidak dapat digunakan dalam playbook:


{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}

Sebagai gantinya, formatnya seperti ini:


[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]

Jika Anda menggunakan entitas di dalam tindakan dan menampilkan hasil Per Entitas, praktik terbaiknya adalah menyusun Hasil JSON seperti ini:


[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]

Selalu pertimbangkan cara penggunaan output tindakan dalam otomatisasi.

Pastikan ada Contoh JSON untuk tindakan Anda.

Contoh JSON digunakan oleh platform di dalam Pembuat Ekspresi selama proses pembuatan playbook. Contoh JSON yang akurat akan membuat pengalaman pembuatan playbook menjadi jauh lebih baik. Hapus informasi PII dari contoh JSON.

Output tindakan (pengayaan entity)

Jika tindakan dijalankan pada entitas, selama eksekusi tindakan, Anda dapat menambahkan metadata tambahan ke entitas tersebut. Struktur metadata tersebut harus mengikuti format ini: {integration identifier}_{key}. Misalnya: WebRisk_is_malicious.

Anda dapat menemukan metadata yang ditambahkan di halaman detail entitas.

Output tindakan (pesan output)

Pesan output harus menjelaskan kepada pengguna bagaimana eksekusi tindakan berjalan dengan cara yang lebih deskriptif. Harus mengarahkan pengguna ke hasil eksekusi tindakan.

Jika beberapa entitas berhasil dipertajam, tetapi yang lain tidak, maka praktik terbaiknya adalah memberikan informasi status untuk setiap entitas yang diberikan dalam pesan.

Jika Anda yakin bahwa terjadi error kritis selama eksekusi tindakan, pastikan ada pesan verbose untuk situasi ini dan gagal melakukan tindakan. Jika tindakan gagal, playbook yang sesuai akan berhenti dieksekusi hingga error diselesaikan atau dilewati secara manual.

Beberapa contoh pesan output:

Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
None of the provided entities were found in VirusTotal.
Successfully executed query "{query}" in Google SecOps.

Jika tindakan harus gagal dan menghentikan eksekusi playbook, maka sebaiknya pesan output memiliki struktur berikut:

"Error executing action "{action name}". Reason: {error}'

Hindari menampilkan seluruh traceback untuk error. Sebaliknya, coba tunjukkan masalah sebenarnya kepada pengguna dalam bahasa alami.

Konektor

Nama

Nama konektor harus mengarahkan pengguna ke data yang akan di-ingest. Secara umum, struktur nama harus seperti ini:

{integration display name} - {data that is being ingested} Connector

Contoh: Crowdstrike - Pull Alerts Connector

Deskripsi

Deskripsi konektor harus menjelaskan kepada pengguna apa yang akan di-ingest oleh konektor; misalnya, Pull alerts from Crowdstrike. Selain itu, Anda perlu memberikan informasi tentang dukungan daftar dinamis; misalnya, Dynamic List works with the display_name parameter.

Deskripsi akhir dalam hal ini akan terlihat seperti ini:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Cobalah untuk membatasi deskripsi hingga 500 karakter.

Parameter Konektor

Parameter konfigurasi konektor harus memiliki nama yang intuitif. Hindari penggunaan karakter khusus dan coba batasi nama parameter tindakan menjadi 2-4 kata.

Deskripsi parameter harus menjelaskan kepada pengguna dampak parameter tersebut terhadap eksekusi konektor.

Jika parameter mendukung jumlah nilai yang didukung yang telah ditentukan sebelumnya, maka di dalam deskripsi berikan bagian berikut: Possible Values: {value 1}, {value 2}. harus memiliki parameter berikut:

Jumlah Maks. Pemberitahuan yang Akan Diambil: menentukan jumlah {object} yang harus diproses selama 1 iterasi konektor.
Maks. {Jam/Hari} Mundur: menentukan waktu mulai pada iterasi pertama konektor. Misalnya, jika Max Hours Backwards disetel ke 1, konektor akan mulai menarik data dari satu jam sebelumnya.
Verifikasi SSL: memverifikasi konektivitas ke API/instance.

Pemetaan Ontologi

Untuk setiap konektor yang dibuat, sebaiknya berikan pemetaan ontologi untuk memverifikasi bahwa pelanggan bersama mendapatkan pengalaman terbaik.

Pemetaan Ontologi digunakan untuk membuat entitas (IOC dan Aset) secara otomatis. Selain itu, metadata penting kolom sistem seperti Waktu Mulai dan Waktu Berakhir ditentukan di sana.

Daftar Dinamis

Daftar dinamis adalah fitur opsional yang memungkinkan Anda membuat filter lanjutan untuk penyerapan. Anda memiliki fleksibilitas untuk membangun logika kustom apa pun dengannya, sekaligus memiliki UX yang unik. Kasus penggunaan yang paling umum adalah menentukan daftar yang diizinkan atau daftar yang diblokir untuk penyerapan.

Jika Anda membuat logika kustom untuk Daftar Dinamis, pastikan logika tersebut diberikan dalam deskripsi konektor. Selain itu, sebaiknya gunakan parameter Gunakan Daftar Dinamis sebagai daftar blokir agar logika terbalik juga didukung.

Pekerjaan

Nama

Nama tugas harus menjelaskan kepada pengguna apa yang dilakukan oleh tugas ini. Secara umum, struktur nama harus seperti ini:

{integration display name} - {process} Job

Contoh: ServiceNow - Sync Incidents Job

Deskripsi

Deskripsi tugas harus menjelaskan kepada pengguna apa yang dilakukan tugas selama iterasi; misalnya, This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Cobalah untuk membatasi deskripsi hingga 500 karakter.

Parameter Tugas

Parameter konfigurasi tugas harus memiliki nama yang intuitif. Hindari penggunaan karakter khusus dan coba batasi nama parameter tindakan menjadi 2-4 kata.

Deskripsi parameter harus menjelaskan kepada pengguna dampak parameter tersebut terhadap eksekusi tugas.

Jika parameter mendukung sejumlah nilai yang didukung yang telah ditentukan sebelumnya, maka di dalam deskripsi berikan bagian berikut:

Possible Values: {value 1}, {value 2}.

Selain parameter autentikasi, semua tugas harus memiliki parameter berikut:

Maks. {Jam/Hari} ke Belakang: menentukan waktu mulai pada iterasi pertama tugas.
Verifikasi SSL: memverifikasi konektivitas ke API/instance.

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