Bermigrasi ke Chronicle API

Didukung di:

Google SecOps SOAR

Dokumen ini berlaku untuk Anda jika Anda memanggil SOAR API secara terprogram menggunakan integrasi, skrip kustom, atau tindakan kustom. Dokumen ini menguraikan langkah-langkah dan pertimbangan untuk membantu Anda memperbarui referensi API terprogram ke endpoint SOAR API baru sebagai bagian dari Chronicle API.

Platform Chronicle API memperkenalkan beberapa peningkatan yang dirancang untuk menyederhanakan proses pengembangan Anda. API ini juga mengatasi batasan dan kompleksitas yang ada di API lama.

API dan kunci API SOAR lama akan tersedia hingga 31 Maret 2027, dan setelah itu tidak akan berfungsi lagi.

Prasyarat

Sebelum melakukan migrasi SOAR API, Anda harus melakukan hal berikut:

• Selesaikan Tahap 1 migrasi.

Perubahan dan peningkatan utama

Tabel berikut menyoroti perbedaan utama antara platform API lama dan baru:

Area fitur	API Lama	API Baru	Detail
Autentikasi	Token API	OAuth 2.0	Metode autentikasi baru ini memberikan keamanan yang lebih baik dan menstandarkan prosesnya.
Model data	Struktur datar	Desain berorientasi resource	Desain baru ini meningkatkan konsistensi data dan menyederhanakan manipulasi objek.
Penamaan endpoint	Tidak konsisten	RESTful dan terstandardisasi	Penamaan yang konsisten membuat API lebih intuitif dan lebih mudah diintegrasikan.

Jadwal penghentian

Platform API lama untuk SOAR dijadwalkan akan sepenuhnya dihentikan pada 31 Maret 2027. Sebaiknya selesaikan migrasi sebelum tanggal tersebut untuk menghindari gangguan layanan.

Langkah-langkah migrasi

Bagian ini menguraikan langkah-langkah untuk berhasil memigrasikan aplikasi Anda ke Chronicle API:

Tinjau dokumentasi

Pahami dokumentasi lengkap untuk API baru, termasuk panduan referensi Chronicle API.

Memetakan endpoint ke platform API baru

Identifikasi endpoint baru yang sesuai untuk setiap panggilan API lama yang dibuat aplikasi Anda. Demikian pula, petakan model data lama ke model data baru, dengan mempertimbangkan perubahan struktural atau kolom baru. Untuk mengetahui detailnya, lihat Tabel pemetaan endpoint API.

Opsional: Membuat integrasi staging

Jika Anda mengedit integrasi kustom atau komponen integrasi komersial, sebaiknya kirim perubahan ke integrasi staging terlebih dahulu. Proses ini memungkinkan Anda melakukan pengujian tanpa memengaruhi alur otomatisasi produksi. Jika Anda memigrasikan aplikasi kustom yang menggunakan SOAR API, Anda dapat langsung melanjutkan ke langkah berikutnya. Untuk mengetahui detail tentang staging integrasi, lihat Menguji integrasi dalam mode staging.

Memperbarui endpoint dan URL layanan

Endpoint layanan adalah URL dasar yang menentukan alamat jaringan layanan API. Satu layanan dapat memiliki beberapa endpoint layanan. Chronicle adalah layanan regional dan hanya mendukung endpoint regional.

Semua endpoint baru menggunakan awalan yang konsisten, sehingga alamat endpoint akhir dapat diprediksi. Contoh berikut menunjukkan struktur URL endpoint baru:

[api_version]/projects/[project_id]/locations/[location]/instances[instance_id]/...

Struktur ini membuat alamat akhir ke endpoint sebagai berikut:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Dengan:

• service_endpoint: Alamat layanan regional
• api_version: Versi API yang akan dikueri. Dapat berupa v1alpha, v1beta, atau v1.
• project_id: Project ID Anda (project yang sama dengan yang Anda tentukan untuk izin IAM)
• location: Lokasi project Anda (region); sama dengan endpoint regional
• instance_id: ID pelanggan Google Security Operations SIEM Anda.

Alamat regional:

• africa-south1: https://chronicle.africa-south1.rep.googleapis.com

• asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

• asia-south1: https://chronicle.asia-south1.rep.googleapis.com

• asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

• asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

• australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

• europe-west12: https://chronicle.europe-west12.rep.googleapis.com

• europe-west2: https://chronicle.europe-west2.rep.googleapis.com

• europe-west3: https://chronicle.europe-west3.rep.googleapis.com

• europe-west6: https://chronicle.europe-west6.rep.googleapis.com

• europe-west9: https://chronicle.europe-west9.rep.googleapis.com

• me-central1: https://chronicle.me-central1.rep.googleapis.com

• me-central2: https://chronicle.me-central2.rep.googleapis.com

• me-west1: https://chronicle.me-west1.rep.googleapis.com

• northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

• southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

• us: https://chronicle.us.rep.googleapis.com

• eu: https://chronicle.eu.rep.googleapis.com

Misalnya, untuk mendapatkan daftar semua kasus pada project di AS:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Memperbarui metode autentikasi

API baru menggunakan Google Cloud IAM untuk autentikasi. Anda harus mengupdate integrasi aplikasi atau respons untuk menerapkan alur autentikasi baru ini. Pastikan pengguna yang menjalankan skrip memiliki izin yang benar untuk endpoint yang ingin diakses. Untuk menerapkan alur baru ini, Anda harus memperbarui integrasi atau aplikasi respons. Pastikan pengguna yang menjalankan skrip memiliki izin yang diperlukan untuk endpoint yang ditargetkan. Untuk mengetahui petunjuk mendetail, lihat halaman Melakukan autentikasi ke Chronicle API.

Memetakan akun layanan atau workload identity ke parameter SOAR

Jika Anda menggunakan akun layanan atau workload identity federation untuk melakukan autentikasi ke Chronicle API, Anda harus mengizinkannya dalam platform untuk memastikan akun tersebut dapat berkomunikasi dengan Google SecOps. Pemetaan ini diperlukan untuk memberikan akses yang diperlukan ke Peran dan Lingkungan SOC kepada akun layanan atau workload identity.

Untuk memberikan akses akun layanan atau akses workload identity federation ke Google SecOps, Anda harus memetakan identitas ke parameter kontrol akses platform. Pemetaan ini adalah langkah wajib untuk memberikan akses yang diperlukan kepada identitas ke Peran SOC, dan Lingkungan yang diperlukan untuk melakukan tugas otomatis atau operasi API.

Catatan: Memberikan peran IAM Google Cloud ke akun layanan atau akun utama diperlukan, tetapi tidak cukup untuk akses Google SecOps SOAR API. Jika akun layanan tidak dipetakan secara eksplisit di Group Mapping, permintaan API akan gagal dengan error 401 UNAUTHENTICATED meskipun semua peran IAM tingkat project yang diperlukan telah dikonfigurasi.

1. Buka Settings > Access Management > Group Mapping.
2. Klik add Add.

3. Lengkapi kolom dalam dialog Add Mapping untuk memetakan identitas ke parameter kontrol akses platform.

   1. Di kolom IdP / User group, masukkan salah satu opsi berikut:
      • Alamat email lengkap akun layanan Anda, jika identitas disiapkan menggunakan Cloud Identity.
      • String akun utama Workload Identity, jika identitas disiapkan menggunakan Workforce Identity Federation.

   2. Konfigurasikan kolom kontrol akses berikut:

      Kolom	Deskripsi
      Grup izin	Pilih grup izin untuk menentukan modul dan submodul yang dapat diakses oleh identitas.
      Peran SOC	Pilih peran SOC untuk menentukan peran identitas (seperti Tingkat 1).
      Lingkungan	Pilih lingkungan atau grup lingkungan yang dapat diakses oleh identitas (seperti Semua Lingkungan).
      Anggota grup	Masukkan email pengguna yang diperlukan jika ada. Tekan Enter setelah menambahkan setiap email.
      Tindakan yang dibatasi	Pilih tindakan yang dibatasi untuk membatasi operasi tertentu dalam modul.

4. Klik Tambahkan.

Untuk mengetahui informasi selengkapnya tentang cara memetakan pengguna dan akun layanan, lihat Memetakan pengguna di platform menggunakan identitas pihak ketiga atau Memetakan pengguna di platform menggunakan Cloud Identity.

Memperbarui logika API

Analisis model data baru dan struktur endpoint yang disediakan dalam referensi API. Tidak semua metode berubah secara signifikan, dan beberapa kode yang ada dapat digunakan kembali. Tujuan utamanya adalah meninjau dokumentasi referensi baru dan, untuk setiap kasus penggunaan tertentu, mengidentifikasi dan menerapkan perubahan yang diperlukan pada nama kolom dan struktur data dalam logika aplikasi Anda.

Menguji integrasi Anda

Uji aplikasi yang telah diupdate dalam integrasi staging sebelum men-deploy ke produksi:

1. Buat rencana pengujian: Tentukan kasus pengujian yang mencakup semua fungsi yang dimigrasikan.
2. Menjalankan pengujian: Jalankan pengujian otomatis dan manual untuk mengonfirmasi akurasi dan validitas.
3. Pantau performa: Nilai performa aplikasi Anda dengan API baru.

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