Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 ke Security Health Analytics.

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

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

Properti spesifik yang wajib dan opsional yang membentuk definisi YAML dibahas dalam Langkah-langkah pembuatan kode.

Menghindari pembuatan detektor yang berlebihan

Untuk mengontrol volume temuan, hindari membuat dan menjalankan modul yang berisi fungsi 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 selengkapnya tentang cara menonaktifkan detektor, lihat Mengaktifkan dan menonaktifkan detektor.

Langkah-langkah pembuatan kode

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 satu kali 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 mengetahui 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. Properti apa pun yang Anda referensikan dalam ekspresi CEL harus ada dalam Google Cloud definisi API setiap jenis resource yang Anda tentukan di bagian resource_selector. Untuk memicu temuan, ekspresi harus diselesaikan 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 yang salah yang dideteksi oleh modul kustom. Penjelasan ini muncul di setiap instance temuan untuk membantu penyelidik memahami masalah yang terdeteksi. Teks harus diapit dalam 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 Google Cloud konsol, 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 nama-nilai. Anda dapat menampilkan nilai properti resource yang dipindai atau string literal. Properti harus ditentukan sebagai resource.PROPERTY_NAME. String literal harus diapit dalam tanda kutip. Contoh berikut menunjukkan custom_output definisi 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 flag --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 terdiri dari 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 mengetahui 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 akan mulai menggunakan modul kustom baru hingga salah satu 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 telah selesai dan 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 ini, 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 deteksinya, ditentukan di 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 memulihkan 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 properti resource dan kebijakan dalam modul kustom

Terlepas dari metode yang Anda gunakan untuk membuat modul kustom—menggunakan Google Cloud konsol atau menulis definisi sendiri—Anda harus dapat mencari properti yang dapat dievaluasi dalam modul kustom. Anda juga harus mengetahui cara mereferensikan properti tersebut dalam definisi modul kustom.

Menemukan properti resource atau kebijakan

Properti Google Cloud resource ditentukan dalam definisi API resource. Anda dapat menemukan definisi ini dengan mengklik nama resource di 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 dimulai dengan resource, diikuti oleh properti induk, dan akhirnya 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 metadata,yang merupakan sub-properti 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 atas.

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 Anda 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 Google Cloud konsol maupun menulis definisi modul kustom sendiri 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. Bagaimanapun, ekspresi harus diselesaikan ke boolean true untuk memicu temuan.

Jika Anda membuat modul kustom di Google Cloud konsol, Anda akan menulis ekspresi ini di Editor ekspresi di halaman Konfigurasi modul.

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

Terlepas dari apakah Anda menggunakan Google Cloud konsol atau file YAML , ekspresi CEL yang mengevaluasi properti resource harus sesuai dengan 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 oleh 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 dalam properti predicate harus berupa Boolean. Temuan hanya akan 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 menggunakan ekspresi ini di Google Cloud konsol dan dalam definisi modul kustom YAML.

Jenis resource	Penjelasan	Ekspresi CEL
Resource apa pun dengan kebijakan IAM	Pemeriksaan kebijakan IAM untuk mengidentifikasi anggota dari domain luar	`!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 dimulai 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 mengizinkan 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 untuk 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 ada dalam daftar 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 dalam cluster Managed Service untuk Apache Spark berisi substring pengujian atau pengembangan	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

Ekspresi CEL untuk properti temuan kustom

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

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

Anda menentukan properti kustom sebagai pasangan name-value.

Jika Anda membuat modul kustom di Google Cloud konsol, Anda akan menentukan pasangan name-value di bagian Properti temuan kustom di halaman Tentukan detail temuan.

Jika Anda membuat kode modul kustom dalam file YAML, Anda akan mencantumkan pasangan name-value sebagai properties di bagian properti custom_output.

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

Tentukan name sebagai string teks tanpa tanda kutip.
Tentukan value sebagai salah satu hal berikut:
- 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 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 berikutnya

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.