Halaman ini diterjemahkan oleh Cloud Translation API.

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 kumpulan properti terstruktur yang Anda gunakan untuk menentukan elemen berikut dari modul kustom Security Health Analytics:

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

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

Menghindari pembuatan detektor yang berlebihan

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

Misalnya, jika Anda membuat modul kustom yang memeriksa kunci enkripsi yang tidak dirotasi setelah 30 hari, sebaiknya nonaktifkan detector Security Health Analytics bawaan KMS_KEY_NOT_ROTATED, karena pemeriksaannya, yang menggunakan nilai 90 hari, akan menjadi tidak perlu.

Untuk informasi selengkapnya tentang cara menonaktifkan detektor, lihat Mengaktifkan dan menonaktifkan detektor.

Langkah-langkah coding

Anda membuat kode definisi modul kustom untuk Security Health Analytics sebagai serangkaian properti YAML, 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 referensikan dalam ekspresi CEL harus ada dalam definisi Google Cloud API untuk setiap jenis resource yang Anda tentukan di bagian resource_selector. Untuk memicu temuan, 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 properti resource dan kebijakan dalam modul kustom.
Buat properti description yang menjelaskan kerentanan atau konfigurasi salah yang terdeteksi oleh modul kustom. Penjelasan ini muncul di setiap instance temuan untuk membantu penyelidik memahami masalah yang terdeteksi. Teks harus diapit dengan tanda petik. 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 petik. 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
```
Secara opsional, buat properti custom_output dan tentukan informasi tambahan yang akan ditampilkan dengan setiap temuan. Tentukan informasi yang akan ditampilkan sebagai satu atau beberapa pasangan nilai nama. Anda dapat menampilkan nilai properti resource yang dipindai atau string literal. Properti harus ditentukan sebagai resource.PROPERTY_NAME. String literal harus diapit 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 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 yang akan 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 file YAML yang berisi definisi modul kustom.
Untuk mengetahui informasi selengkapnya tentang cara menggunakan modul kustom Security Health Analytics, lihat Menggunakan modul kustom untuk Security Health Analytics.

Memindai latensi untuk modul kustom baru

Membuat modul kustom tidak akan memicu pemindaian baru.

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

Pemindaian batch pertama setelah Anda membuat modul kustom. Bergantung pada waktu pembuatan 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 akan memicu pemindaian real-time.

Contoh definisi modul kustom

Contoh berikut menunjukkan definisi modul kustom yang 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 di bagian resource_types.
Pemeriksaan yang dilakukan modul pada resource, logika deteksi-nya, ditentukan di bagian predicate yang didahului 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 di properti recommendation. Karena tanda petik muncul dalam panduan, karakter escape garis miring terbalik diperlukan sebelum setiap tanda petik.

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 properti resource dan kebijakan dalam modul kustom

Terlepas dari metode yang Anda gunakan untuk membuat modul kustom—dengan menggunakan Konsol Google Cloud 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 di Jenis resource yang didukung.

Anda dapat menemukan properti kebijakan dalam dokumentasi referensi IAM API. 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 oleh 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 dari 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 tingkat teratas.

Berikut adalah contoh properti kebijakan IAM dan cara mendapatkannya:

policy.bindings, dengan bindings adalah properti dari policy.
policy.version, dengan version adalah properti dari 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 atau menulis sendiri definisi modul kustom dalam file YAML, ekspresi CEL yang Anda tentukan akan 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 Anda dapat berupa pemeriksaan sederhana dari satu nilai atau ekspresi gabungan yang lebih kompleks yang memeriksa beberapa nilai atau kondisi. Apa pun caranya, ekspresi harus di-resolve ke true boolean untuk memicu temuan.

Jika membuat modul kustom di konsol Google Cloud, Anda akan menulis ekspresi ini di Expression editor di halaman Configure module.

Jika Anda membuat kode modul kustom dalam file YAML, tambahkan ekspresi ini di bagian properti predicate.

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

Properti yang Anda tentukan dalam ekspresi CEL harus berupa 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 modul kustom.

Misalnya, jika Anda menentukan modul kustom yang disebut 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 dibagikan 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 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 konsol Google Cloud dan dalam definisi modul kustom YAML.

Jenis aset	Explanation	Ekspresi CEL
Resource apa pun 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	Memeriksa 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 fungsi Cloud Run	`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 mengizinkan API terkait penyimpanan yang diaktifkan	`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`	Memeriksa apakah ID project di cluster Dataproc berisi substring pengujian atau pengembangan	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Ekspresi CEL untuk properti penemuan kustom

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

Properti kustom muncul di properti sumber temuan dalam JSON-nya dan di tab Source properties pada detail temuan di konsol Google Cloud.

Anda menentukan properti kustom sebagai pasangan name-value.

Jika membuat modul kustom di konsol Google Cloud, Anda menentukan pasangan name-value di bagian Custom finding properties di halaman Define finding details.

Jika membuat kode modul kustom dalam file YAML, Anda mencantumkan pasangan name-value sebagai properties di bagian 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 dari properti yang berisi nilai yang akan ditampilkan.
- PROPERTY_TO_RETURN adalah properti yang berisi nilai yang akan ditampilkan.
- Untuk menampilkan string teks, sertakan string tersebut dalam tanda kutip.

Contoh berikut menunjukkan dua pasangan name-value yang ditentukan dengan benar di bagian 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, mengirimkan, melihat, dan memperbarui modul kustom, lihat halaman berikut:

Untuk menguji modul kustom, lihat Menguji modul kustom untuk Security Health Analytics.
Untuk mengupload, melihat, dan memperbarui modul kustom, lihat Membuat dan mengelola modul kustom untuk Security Health Analytics.