Membuat kode modul kustom untuk Security Health Analytics

Halaman ini menjelaskan cara membuat kode definisi modul kustom menggunakan Common Expression Language (CEL) dan YAML.

Gunakan Google Cloud CLI untuk mengupload definisi modul kustom Anda ke Security Health Analytics.

Dalam file YAML, definisi modul kustom terdiri dari serangkaian properti terstruktur yang Anda gunakan untuk menentukan elemen berikut pada modul kustom Security Health Analytics:

Resource yang akan dipindai.
Logika deteksi yang akan digunakan.
Informasi untuk diberikan kepada tim keamanan agar mereka dapat dengan cepat memahami, melakukan triase, dan menyelesaikan masalah yang terdeteksi.

Properti wajib dan opsional khusus yang membentuk definisi YAML dibahas dalam Langkah-langkah coding.

Menghindari pembuatan pendeteksi redundan

Untuk mengontrol penemuan volume, hindari membuat dan menjalankan modul yang berisi fungsi yang berlebihan.

Misalnya, jika Anda membuat modul kustom yang memeriksa kunci enkripsi yang tidak dirotasi setelah 30 hari, pertimbangkan untuk menonaktifkan detektor Security Health Analytics bawaan KMS_KEY_NOT_ROTATED, karena pemeriksaannya, yang menggunakan nilai 90 hari, akan berlebihan.

Untuk mengetahui informasi lebih lanjut tentang cara menonaktifkan detektor, baca artikel Mengaktifkan dan menonaktifkan detektor.

Langkah-langkah coding

Anda membuat kode definisi modul kustom untuk Security Health Analytics sebagai serangkaian properti YAML, yang beberapa di antaranya berisi ekspresi CEL.

Untuk membuat kode modul definisi kustom, ikuti langkah-langkah berikut:

Buat file teks dengan ekstensi nama file yaml.
Dalam file teks, buat properti resource_selector dan tentukan satu hingga lima jenis resource untuk dipindai oleh modul kustom. Jenis resource tidak dapat ditentukan lebih dari sekali dalam definisi modul kustom. Contoh:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
Jenis resource yang Anda tentukan harus didukung oleh Security Command Center. Untuk daftar jenis resource yang didukung, lihat Jenis resource yang didukung.
Buat properti predicate dan tentukan satu atau beberapa ekspresi CEL yang memeriksa properti jenis resource yang akan dipindai. Setiap properti yang Anda rujuk dalam ekspresi CEL harus ada dalam definisi Google Cloud API dari setiap jenis resource yang Anda tentukan di resource_selector. Untuk memicu penemuan, ekspresi harus di-resolve ke TRUE. Misalnya, dalam ekspresi berikut, hanya nilai rotationPeriod yang lebih besar dari 2592000s yang memicu temuan.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Untuk mendapatkan bantuan dalam menulis ekspresi CEL, lihat referensi berikut:
- Jenis resource yang didukung. Klik setiap resource untuk melihat properti yang dapat Anda gunakan dalam ekspresi CEL.
- Menulis ekspresi CEL.
- Mereferensikan resource dan properti kebijakan dalam modul kustom.
Buat properti description yang menjelaskan kerentanan atau kesalahan konfigurasi yang terdeteksi oleh modul kustom. Penjelasan ini muncul di setiap instance temuan untuk membantu penyelidik memahami masalah yang terdeteksi. Teks harus diapit dengan tanda kutip. Contoh:
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
Buat properti recommendation yang menjelaskan cara memperbaiki masalah yang terdeteksi. Gcloud CLI memerlukan karakter escape sebelum karakter tertentu, seperti tanda kutip. Contoh berikut menunjukkan penggunaan garis miring terbalik untuk meng-escape setiap kumpulan tanda kutip:
```
recommendation: "To fix this issue go to
  https://console.cloud.google.com/security/kms. Click the key-ring that
  contains the key. Click the key. Click \"Edit rotation period\". Then
  set the rotation period to at most 30 days."
```
Jika Anda membuat atau memperbarui modul kustom menggunakan Konsol Google Cloud, karakter escape tidak diperlukan.
Buat properti severity dan tentukan tingkat keparahan default untuk temuan yang dibuat oleh modul ini. Nilai yang umum digunakan untuk properti severity adalah LOW, MEDIUM, HIGH, dan CRITICAL. Misalnya,
```
severity: MEDIUM
```
Jika ingin, buat properti custom_output dan tentukan informasi tambahan untuk ditampilkan dengan setiap temuan. Tentukan informasi yang akan ditampilkan sebagai satu atau beberapa pasangan nama-nilai. Anda dapat menampilkan nilai properti resource yang dipindai atau string literal. Properti harus ditentukan sebagai resource.PROPERTY_NAME. String literal harus disertai tanda kutip. Contoh berikut menunjukkan definisi custom_output yang menampilkan nilai properti, nilai rotationPeriod dalam resource CryptoKey yang dipindai, dan string teks, "Excessive rotation period for CryptoKey":
```
 custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "Excessive rotation period for CryptoKey"
```
Simpan file ke lokasi yang dapat diakses oleh gcloud CLI Anda.
Upload definisi ke Security Health Analytics dengan perintah berikut:
```
 gcloud scc custom-modules sha create \
     --organization=organizations/ORGANIZATION_ID \
     --display-name="MODULE_DISPLAY_NAME" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=DEFINITION_FILE_NAME.yaml
```
Ganti nilai berikut:
- ORGANIZATION_ID dengan ID organisasi induk modul kustom atau ganti tanda --organization dengan --folders atau --project dan tentukan ID folder atau project induk.
- MODULE_DISPLAY_NAME dengan nama untuk ditampilkan sebagai kategori temuan saat modul kustom menampilkan temuan. Nama harus antara 1 hingga 128 karakter, diawali dengan huruf kecil, dan hanya berisi karakter alfanumerik atau garis bawah.
- DEFINITION_FILE_NAME dengan jalur dan nama file YAML yang berisi definisi modul kustom.
Untuk informasi selengkapnya tentang cara menggunakan modul kustom Security Health Analytics, lihat Menggunakan modul kustom untuk Security Health Analytics.

Latensi pemindaian untuk modul kustom baru

Membuat modul kustom tidak akan memicu pemindaian baru.

Security Health Analytics tidak mulai menggunakan modul kustom baru hingga salah satu hal berikut:

Pemindaian batch pertama setelah Anda membuat modul kustom. Bergantung pada kapan Anda membuat modul kustom dalam jadwal pemindaian batch, Anda mungkin harus menunggu hingga 24 jam sebelum Security Health Analytics mulai menggunakan modul kustom.
Perubahan pada resource target memicu pemindaian real-time.

Contoh definisi modul kustom

Contoh berikut menunjukkan definisi modul kustom lengkap yang memicu temuan jika nilai properti rotationPeriod dari resource cloudkms.googleapis.com/CryptoKey lebih besar dari 2.592.000 detik (30 hari). Contoh ini menampilkan dua nilai opsional di bagian custom_output: nilai resource.rotationPeriod dan catatan sebagai string teks.

Dalam contoh, perhatikan elemen berikut:

Jenis aset atau resource yang akan diperiksa tercantum di bagian resource_selector pada resource_types.
Pemeriksaan yang dilakukan modul pada resource, logika deteksinya, ditentukan dalam bagian predicate yang diawali dengan expression.
Dua properti sumber kustom, duration dan violation, ditentukan di bagian custom_output.
Penjelasan masalah yang terdeteksi ditentukan dalam properti description.
Panduan untuk memperbaiki masalah yang terdeteksi ditentukan pada properti recommendation. Karena tanda kutip muncul dalam panduan, karakter escape garis miring terbalik diperlukan sebelum setiap tanda kutip.

severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
  resource_types:
  - cloudkms.googleapis.com/CryptoKey
predicate:
  expression: resource.rotationPeriod > duration("2592000s")
custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.rotationPeriod
    - name: violation
      value_expression:
        expression:
          "Excessive rotation period for CryptoKey"

Mereferensikan resource dan properti kebijakan dalam modul khusus

Apa pun metode yang digunakan untuk membuat modul kustom—dengan menggunakan Google Cloud Console atau dengan menulis definisi sendiri—Anda harus dapat mencari properti yang dapat dievaluasi dalam modul kustom. Anda juga perlu mengetahui cara mereferensikan properti tersebut dalam definisi modul kustom.

Menemukan properti resource atau kebijakan

Properti resource Google Cloud ditentukan dalam definisi API resource. Anda dapat menemukan definisi ini dengan mengklik nama resource pada Jenis resource yang didukung.

Anda dapat menemukan properti kebijakan di dokumentasi referensi API IAM. Untuk properti kebijakan, lihat Kebijakan.

Mereferensikan properti resource dalam definisi modul kustom

Saat Anda membuat modul kustom, semua referensi langsung ke properti resource yang dipindai harus diawali dengan resource, diikuti dengan properti induk, dan terakhir properti target. Properti dipisahkan dengan titik, menggunakan notasi titik gaya JSON.

Berikut adalah contoh properti resource dan cara mengambilnya:

resourceName: menyimpan nama lengkap resource di Inventaris Aset Cloud, misalnya, //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: dengan rotationPeriod adalah properti resource.
resource.metadata.name: dengan name adalah sub-properti dari metadata, yang merupakan sub-properti dari resource.

Mereferensikan properti kebijakan IAM

Anda dapat membuat ekspresi CEL yang mengevaluasi kebijakan IAM resource dengan mereferensikan properti kebijakan IAM resource. Satu-satunya properti yang tersedia adalah binding dan peran dalam binding.

Saat mereferensikan properti kebijakan IAM, policy adalah properti level teratas.

Berikut adalah contoh properti kebijakan IAM dan cara mengambilnya:

policy.bindings, dengan bindings adalah properti policy.
policy.version, dengan version adalah properti policy.

Untuk contoh lainnya, lihat Contoh ekspresi CEL.

Untuk mengetahui informasi tentang properti kebijakan, lihat Kebijakan.

Menulis ekspresi CEL

Saat membuat modul kustom, Anda menggunakan ekspresi CEL untuk mengevaluasi properti resource yang dipindai. Secara opsional, Anda juga dapat menggunakan ekspresi CEL untuk menentukan pasangan name-value kustom yang menampilkan informasi tambahan dengan temuan Anda.

Baik Anda membuat modul kustom di Konsol Google Cloud maupun menulis sendiri definisi modul kustom dalam file YAML, ekspresi CEL yang Anda tentukan akan tetap sama.

Ekspresi CEL untuk logika deteksi

Anda membuat kode logika deteksi modul kustom menggunakan ekspresi CEL dengan operator CEL standar untuk mengevaluasi properti resource yang dipindai.

Ekspresi dapat berupa pemeriksaan sederhana terhadap satu nilai atau ekspresi gabungan yang lebih kompleks dan memeriksa beberapa nilai atau kondisi. Apa pun itu, ekspresi harus di-resolve ke boolean true untuk memicu temuan.

Jika Anda membuat modul kustom di Konsol Google Cloud, tulis ekspresi ini di Expression editor di halaman Configure module.

Jika Anda melakukan coding modul kustom dalam file YAML, tambahkan ekspresi ini di bawah properti predicate.

Terlepas dari apakah Anda menggunakan konsol Google Cloud atau file YAML, ekspresi CEL yang mengevaluasi properti resource, harus mematuhi aturan berikut:

Properti yang Anda tentukan dalam ekspresi CEL harus merupakan properti resource yang dipindai, seperti yang ditentukan dalam definisi API jenis resource.
Jika modul kustom mengevaluasi beberapa jenis resource, properti yang Anda tentukan dalam ekspresi CEL harus sama untuk setiap jenis resource yang dievaluasi oleh modul kustom.

Misalnya, jika Anda menentukan modul kustom bernama invalid_cryptokey yang memeriksa dua jenis resource: cloudkms.googleapis.com/CryptoKey dan cloudkms.googleapis.com/CryptoKeyVersion, Anda dapat menulis ekspresi berikut, karena jenis resource CryptoKey dan CryptoKeyVersion menyertakan properti name:
```
predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
```
Namun, Anda tidak dapat menentukan ekspresi berikut dalam modul kustom invalid_cryptokey karena properti importTime dan rotationPeriod yang dievaluasi ekspresi tidak digunakan oleh kedua jenis resource:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Semua enum dalam ekspresi CEL harus direpresentasikan sebagai string. Misalnya, berikut ini adalah ekspresi yang valid untuk jenis resource cloudkms.googleapis.com/CryptoKeyVersion:
```
resource.state = "PENDING_GENERATION"
```
Hasil ekspresi CEL yang Anda tentukan di properti predicate harus berupa Boolean. Temuan hanya dipicu jika hasilnya adalah true.

Untuk mengetahui informasi selengkapnya tentang CEL, lihat referensi berikut:

Contoh ekspresi CEL

Tabel berikut mencantumkan beberapa ekspresi CEL yang dapat digunakan untuk mengevaluasi properti resource. Anda dapat menggunakannya di Google Cloud Console dan dalam definisi modul kustom YAML.

Jenis aset	Penjelasan	Ekspresi CEL
Semua resource dengan kebijakan IAM	Pemeriksaan kebijakan IAM untuk mengidentifikasi anggota dari luar domain	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	Pemeriksaan periode rotasi kunci Cloud KMS	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
Beberapa jenis resource dengan satu kebijakan	Periksa apakah nama resource diawali dengan `dev` atau `devAccess` berdasarkan jenis resource	`(resource.type == 'compute.googleapis.com/Disk' && resource.name.startsWith('projects/PROJECT_ID/regions/ REGION/disks/devAccess')) \|\| (resource.type == 'compute.googleapis.com/Instance ' && resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-'))`
`compute.googleapis.com/Network`	Aturan peering Virtual Private Cloud untuk mencocokkan peer jaringan	`resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') \|\| resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$'))`
`cloudfunctions.googleapis.com/CloudFunction`	Hanya izinkan traffic masuk internal untuk Cloud Function	`has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')`
`compute.googleapis.com/Instance`	Nama resource cocok dengan pola	`resource.name.matches('^gcp-vm-(linux\|windows)-v\\d+$')`
`serviceusage.googleapis.com/Service`	Hanya izinkan pengaktifan API terkait penyimpanan	`resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') \|\| resource.name.matches('bigquery-json.googleapis.com') \|\| resource.name.matches('bigquery.googleapis.com') \|\| resource.name.matches('sql-component.googleapis.com') \|\| resource.name.matches('spanner.googleapis.com'))`
`sqladmin.googleapis.com/Instance`	Hanya IP publik yang diizinkan yang diizinkan	`(resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' \|\| ip.ipAddress.matches('IP_ADDRESS'))))`
`dataproc.googleapis.com/Cluster`	Periksa apakah project ID di cluster Dataproc berisi pengujian atau pengembangan substring	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Ekspresi CEL untuk properti temuan kustom

Secara opsional, untuk menampilkan informasi tambahan pada setiap temuan yang dapat digunakan dalam menemukan kueri, Anda dapat menentukan hingga sepuluh properti kustom yang akan ditampilkan dengan temuan yang dihasilkan oleh modul kustom.

Properti khusus muncul di properti sumber temuan di JSON-nya dan di tab Properti sumber pada detail temuan di Konsol Google Cloud.

Anda menentukan properti kustom sebagai pasangan name-value.

Jika Anda membuat modul kustom di Konsol Google Cloud, tentukan pasangan name-value di bagian Properti penemuan kustom di halaman Menentukan detail temuan.

Jika Anda membuat kode modul kustom dalam file YAML, cantumkan pasangan name-value sebagai properties pada properti custom_output.

Terlepas dari apakah Anda menggunakan konsol Google Cloud atau file YAML, aturan berikut berlaku:

Tentukan name sebagai string teks tanpa tanda kutip.
Tentukan value sebagai salah satu dari berikut ini:
- Untuk menampilkan nilai properti, tentukan properti dalam format berikut:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Pada contoh ini:
- RESOURCE_TYPE dapat berupa resource atau policy.
- PROPERTY Satu atau beberapa properti induk properti yang berisi nilai yang akan ditampilkan.
- PROPERTY_TO_RETURN adalah properti yang berisi nilai yang akan ditampilkan.
- Untuk mengembalikan string teks, kurung string dalam tanda kutip.

Contoh berikut menunjukkan dua pasangan name-value yang ditentukan dengan benar di custom_output dalam file YAML:

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "Note content"

Langkah selanjutnya

Untuk menguji, mengirim, melihat, dan memperbarui modul kustom, lihat halaman berikut:

Untuk menguji modul kustom, lihat Menguji modul kustom untuk Analisis Kondisi Keamanan.
Untuk mengupload, melihat, dan memperbarui modul kustom, lihat Membuat dan mengelola modul kustom untuk Analisis Kondisi Keamanan.