Berkontribusi pada integrasi respons komunitas

Didukung di:

Dokumen ini menguraikan panduan untuk mengirimkan Integrasi Respons ke Google SecOps melalui kontribusi komunitas. Semua integrasi yang dikirimkan akan menjalani proses pemeriksaan oleh tim Google SecOps resmi, dengan fokus 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 kosong; misalnya, Vertex AI, bukan VertexAI.

ID Integrasi

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

ID tersedia di sebagian besar tempat di seluruh platform.

Deskripsi

The Deskripsi harus memberikan ringkasan tingkat tinggi produk yang digunakan untuk membuat integrasi dan tidak boleh melebihi 500 karakter. Deskripsi harus berisi informasi berikut:

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

Jangan menyertakan URL dalam deskripsi.

Logo

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

Anda harus memvalidasi logo di halaman berikut:

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

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

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

Parameter konfigurasi

Semua integrasi harus berisi parameter konfigurasi (Parameter Root API + Autentikasi parameter), 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 harus membantu pengguna mengonfigurasi integrasi dari dalam platform. Jangan menyertakan 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, status konektivitas yang akurat akan ditampilkan.

Catatan rilis

Struktur umum untuk 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 skenario:

  • Jika 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 tugas baru ditambahkan: New Job Added - {job name}
  • Jika widget yang telah ditentukan sebelumnya ditambahkan ke tindakan: {action name} - Added Predefined Widget.
  • Jika widget yang telah ditentukan sebelumnya 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, Anda harus menentukan REGRESSIVE! dalam catatan rilis. Misalnya, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

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

Pembuatan Versi

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

Tag

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

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

The Name of the action should point to the activity that is being performed; for example, Get Case Details, List Entity Events, or Execute Search.

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

Nama tindakan harus disampaikan dalam 2-3 kata.

Deskripsi

Deskripsi tindakan harus menunjukkan 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.

Coba batasi deskripsi hingga 500 karakter.

Parameter tindakan

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

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

Output tindakan (hasil skrip)

Hasil skrip harus mewakili hasil sederhana dari tindakan. Pada umumnya, hasil skrip hanya boleh 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 tindakan yang paling penting. Semua data yang tersedia dalam hasil JSON akan dapat diakses selama eksekusi playbook. Pastikan objek JSON yang valid didorong ke output.

Ukuran Hasil JSON memiliki batas 15 MB.

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


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

Sebagai gantinya, formatnya harus 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 output tindakan dapat digunakan di 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 pembuatan playbook menjadi jauh lebih baik. Hapus informasi PII dari contoh JSON.

Output tindakan (pengayaan entitas)

Jika tindakan dieksekusi pada entitas, Anda dapat menambahkan metadata tambahan ke entitas tersebut selama eksekusi tindakan. Struktur metadata tersebut harus mengikuti format ini: {integration identifier}_{key}. Contoh: 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. Pesan output harus mengarahkan pengguna ke hasil eksekusi tindakan.

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

Jika Anda yakin bahwa error penting terjadi selama eksekusi tindakan, pastikan ada pesan verbose untuk situasi ini dan gagalkan 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, sebaiknya pesan output memiliki struktur berikut:

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

Hindari menyertakan seluruh traceback untuk error. Sebagai gantinya, coba arahkan pengguna ke masalah sebenarnya dalam bahasa natural.

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 menunjukkan kepada pengguna apa yang akan di-ingest oleh konektor; misalnya, Pull alerts from Crowdstrike. Selain itu, Anda harus 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.

Coba batasi deskripsi hingga 500 karakter.

Parameter Konektor

Parameter konfigurasi konektor harus memiliki nama yang intuitif. Hindari penggunaan karakter khusus dan coba batasi nama parameter tindakan hingga 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, berikan bagian berikut di dalam deskripsi: Possible Values: {value 1}, {value 2}. harus memiliki parameter berikut:

  • Max Alerts To Fetch: menentukan jumlah {object} yang harus diproses selama 1 iterasi konektor.
  • Max {Hours/Days} Backwards: menentukan waktu mulai pada iterasi pertama konektor. Misalnya, jika Max Hours Backwards ditetapkan ke 1, konektor akan mulai menarik data dari satu jam sebelumnya.
  • Verify SSL: memverifikasi konektivitas ke API/instance.

Pemetaan Ontologi

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

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

Daftar Dinamis

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

Jika Anda membuat logika kustom untuk Daftar Dinamis, pastikan bahwa logika tersebut diberikan dalam deskripsi konektor. Selain itu, sebaiknya sertakan parameter Use Dynamic List as a blocklist untuk mendukung logika terbalik.

Pekerjaan

Nama

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

  • {integration display name} - {process} Job
    • Contoh: ServiceNow - Sync Incidents Job

Deskripsi

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

Coba batasi deskripsi hingga 500 karakter.

Parameter Pekerjaan

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

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

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

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

Selain parameter autentikasi, semua pekerjaan harus memiliki parameter berikut:

  • Max {Hours/Days} Backwards: menentukan waktu mulai pada iterasi pertama pekerjaan.
  • Verify SSL: memverifikasi konektivitas ke API/instance.

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