Sintaksis bagian kecocokan

Didukung di:

Google SecOps SIEM

Di YARA-L 2.0, bagian match menyediakan mekanisme untuk korelasi multi-peristiwa. Fitur ini menentukan logika untuk mengelompokkan peristiwa ke dalam satu deteksi dengan menautkan atribut umum, seperti pengguna, alamat IP, atau hash file, dalam batas waktu tertentu.

Anda menggunakan bagian match untuk kasus penggunaan berikut:

• Tautkan dua peristiwa berbeda atau lebih dalam suatu aturan.
• Menggabungkan data di Penelusuran dan Dasbor, seperti menghitung upaya login yang gagal selama jangka waktu tertentu.

Menentukan kriteria korelasi

Gunakan untuk menentukan kriteria korelasi ini dengan menentukan hal berikut:

• Mengelompokkan kolom (kunci): Variabel (seperti $user atau $ip) yang harus memiliki nilai yang identik di seluruh peristiwa (ditentukan di bagian events) untuk memicu kecocokan.

• Batasan waktu: Durasi jendela tempat peristiwa yang dikelompokkan harus terjadi untuk memenuhi aturan atau penggabungan. Di Aturan, ini menentukan jendela deteksi; di Penelusuran dan Dasbor, ini menentukan jendela agregasi atau korelasi.

Membandingkan persyaratan fitur

Tabel berikut menjelaskan perbandingan untuk Aturan ke Penelusuran dan Dasbor.

Fitur	Persyaratan aturan	Dukungan Penelusuran dan Dasbor
Jenis variabel	Harus menggunakan placeholder yang ditentukan di bagian events.	Mendukung placeholder dan kolom UDM langsung.
Periode waktu	Menentukan batas deteksi.	Menentukan bucket agregasi atau korelasi.
Sintaksis	over <number><m/h/d> (misalnya, 10m, 2h, 1d)	over <number><m/h/d>
Batas	Min: 1m / Maks: 48h	Min: 1m / Maks: 48h

Jenis jendela yang didukung

YARA-L 2.0 menggunakan perilaku windowing yang berbeda untuk menentukan cara waktu dibagi dan cara peristiwa dikelompokkan. Anda dapat mengelompokkan kolom dan placeholder peristiwa di bagian match menurut perincian waktu yang ditentukan menggunakan salah satu rentang waktu yang didukung berikut.

Jenis jendela yang didukung	Sintaksis	Deskripsi	Kasus penggunaan umum
Hop	$key over <duration>	Interval waktu yang tumpang-tindih (perilaku default).	Korelasi umum dari beberapa peristiwa.
Berguling	$key by <duration> tumbling	Interval waktu berukuran tetap, tidak tumpang-tindih, dan berkelanjutan.	Mengukur aktivitas dalam blok hingga 1 jam (misalnya, $user by 30m).
Menggeser	$key over <duration> [before|after] $pivot	Interval waktu yang ditambatkan ke peristiwa "pivot" tertentu.	Pengurutan ketat (misalnya, File Download after Login).

Contoh sintaksis:

match:
  $user, $source_ip over 5m  // Groups events by user and IP within a 5-minute window

Jendela hop

Periode lompatan adalah perilaku default untuk aturan multi-peristiwa. Hal ini membuat interval waktu yang tumpang-tindih untuk memastikan peristiwa yang terjadi di dekat batas jendela tidak terlewat.

• Sintaksis: $key over <duration> (misalnya, $user over 30m)
• Kasus penggunaan: Terbaik untuk deteksi saat Anda perlu memastikan bahwa skenario tertentu terdeteksi, terlepas dari kapan tepatnya interval jendela dimulai atau berakhir.
• Dukungan: Didukung untuk agregasi dalam penelusuran dan dasbor (misalnya, count).

Secara default, kueri YARA-L dengan bagian match menggunakan hop window untuk mengorelasikan beberapa peristiwa dari waktu ke waktu. Rentang waktu eksekusi kueri dibagi menjadi serangkaian jendela hop tetap yang tumpang-tindih. Meskipun durasi jendela ini ditentukan di bagian match, interval tumpang-tindih dan penyelarasan jendela ditentukan oleh sistem dan tidak dapat dikonfigurasi oleh pengguna. Peristiwa kemudian dikorelasikan dalam setiap jangka waktu yang telah ditentukan ini.

Contoh: Jendela lompatan yang tumpang-tindih untuk korelasi berkelanjutan

Contoh berikut menunjukkan kueri yang dijalankan selama rentang waktu [1.00, 2.00], dengan bagian match $user over 30m, di mana kemungkinan kumpulan jendela hop yang tumpang-tindih yang dapat dibuat adalah [1.00, 1.30], [1.03, 1.33], dan [1.06, 1.36].

rule hop_window_brute_force_example {
meta:
  description = "Detects multiple failed logins within a shifting 30-minute window."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.user.userid = $user

match:
  // This creates the overlapping windows (e.g., 1:00-1:30, 1:03-1:33)
  $user over 30m

condition:
  // This will trigger if 10 or more failures fall into any single 30m hop
  #login >= 10
}

Contoh: Korelasi multi-peristiwa menggunakan jendela hop

Contoh berikut menunjukkan nilai default untuk sebagian besar aturan multi-peristiwa. Hal ini mencatat peristiwa yang terjadi dalam jangka waktu umum yang sama.

rule hop_window_example {
meta:
  description = "Detect a user with a failed login followed by a success within 30m"

events:
  $e1.metadata.event_type = "USER_LOGIN"
  $e1.extensions.auth.auth_status = "FAILURE"
  $e1.principal.user.userid = $user

  $e2.metadata.event_type = "USER_LOGIN"
  $e2.extensions.auth.auth_status = "SUCCESS"
  $e2.principal.user.userid = $user

match:
  $user over 30m  // This is a hop window

condition:
  $e1 and $e2
}

Contoh: perbandingan jendela hop

Untuk mengidentifikasi upaya brute force, jendela 10m mengelompokkan semua kegagalan USER_LOGIN. Kemudian, condition mengevaluasi apakah jumlah (#e) dalam bucket 10 menit tertentu tersebut melebihi nilai minimum Anda.

rule failed_logins
{
meta:
  author = "Security Team"
  description = "Detects multiple failed user logins within 10-minute windows."
  severity = "HIGH"

events:
  $e.metadata.event_type = "USER_LOGIN"
  $e.security_result.action = "FAIL"
  $user = $e.target.user.userid

match:
  $user over 10m

condition:
  #e >= 5
}

Bagian match menemukan pengguna yang gagal login di lokasi baru selama interval 10 menit (10m):

match:
  $user over 10m

Periode tumbling

Periode tumbling menyegmentasikan aliran data ke dalam interval waktu berukuran tetap, tidak tumpang-tindih, dan berkelanjutan. Setiap peristiwa data hanya ditetapkan ke satu jendela. Hal ini berbeda dengan jendela geser atau lompat, yang dapat memiliki interval waktu yang tumpang-tindih.

• Sintaksis: Gunakan operator by ($key by <duration>), misalnya, $user by 30m.
• Kasus penggunaan: Paling cocok untuk pelaporan dan pembuatan dasbor saat Anda ingin menghitung peristiwa dalam blok yang berbeda (misalnya, "How many alerts per hour?").
• Penelusuran dan dasbor: Sering digunakan untuk membuat diagram batang yang bersih tanpa menghapus duplikat peristiwa.

Contoh: Penghitungan interval tetap dengan jendela bergulir

Contoh berikut menunjukkan periode tumbling 30 menit, di mana peristiwa yang terjadi antara 1:00:00 dan 1:29:59 diproses bersama-sama. Kemudian, kumpulan peristiwa berikutnya, dari 1:30:00 hingga 1:59:59, diproses secara terpisah.

rule tumbling_window_threshold_example {
meta:
  description = "Detect more than 50 failed logins from a single IP within a fixed 1-hour block."
  severity = "Medium"

events:
  $login.metadata.event_type = "USER_LOGIN"
  $login.extensions.auth.auth_status = "FAILURE"
  $login.principal.ip = $ip

match:
// This creates distinct, 1-hour blocks (e.g., 1:00-1:59, 2:00-2:59)
  $ip by 1h

condition:
  #login > 50
}

Jendela geser

Gunakan jendela geser saat Anda perlu menelusuri peristiwa yang terjadi dalam urutan relatif yang ketat (misalnya, e1 terjadi hingga dua menit setelah e2). Tidak seperti jendela tetap, jendela geser dipicu oleh setiap kemunculan $pivot_event yang ditentukan menggunakan sintaksis ini:

• after: Jendela dimulai pada stempel waktu peristiwa poros dan diperluas ke depan.
• before: Jendela berakhir pada stempel waktu peristiwa poros dan meluas ke belakang.

Tentukan periode geser di bagian match kueri sebagai berikut:

<match-var-1>, <match-var-2>, ... over <duration> [before|after] <pivot-event-var>

• Sintaksis: $key over <duration> before|after $<pivot_event>
• Kunci pengelompokan: Kolom umum (misalnya, $user, $ip) yang digunakan untuk menautkan peristiwa.
• Durasi: Perbedaan waktu dari peristiwa poros (misalnya, 5m, 1h).
• Kasus penggunaan:
  • Pengurutan ketat: Mendeteksi rangkaian serangan yang memerlukan urutan (misalnya, pembuatan pengguna yang diikuti dengan eskalasi hak istimewa).
  • Waktu relatif: Temukan peristiwa yang terjadi dalam offset tertentu dari "pemicu" (misalnya, peristiwa Process Start diikuti dengan Network Connection dalam waktu 30 detik).
  • Deteksi tidak adanya: Mengidentifikasi kapan peristiwa "pembersihan" atau "detak jantung" yang diperlukan gagal terjadi setelah peristiwa mulai (misalnya, Database Backup Start tanpa peristiwa End yang sesuai).

Catatan: Jendela geser hanya tersedia untuk aturan, bukan di penelusuran atau dasbor.

Contoh jendela geser yang valid

Contoh berikut menunjukkan jendela geser yang valid:

$var1, $var2 over 5m after $e1 $user over 1h before $e2 $host, $ip over 1h before $e2

Contoh: Korelasi yang berorientasi ke depan dengan jendela geser (after)

Contoh berikut menunjukkan cara mendeteksi urutan peristiwa di mana peristiwa kedua harus terjadi dalam jangka waktu tertentu setelah peristiwa "pemicu" atau pivot utama. Hal ini berguna untuk mendeteksi pergerakan lateral yang cepat atau tindakan lanjutan otomatis.

rule sliding_window_after_example {
meta:
  description = "Detect a network connection occurring within 1 minute after a suspicious process launch."
  severity = "High"

events:
  $proc.metadata.event_type = "PROCESS_LAUNCH"
  $proc.principal.hostname = $host

  $net.metadata.event_type = "NETWORK_HTTP"
  $net.principal.hostname = $host

match:
  // $proc is the pivot; the 1-minute window starts at the $proc timestamp
  $host over 1m after $proc

condition:
  $proc and $net
}

Contoh: Korelasi yang melihat ke belakang dengan jendela geser (before)

Gunakan jendela geser "before" untuk menyelidiki aktivitas yang menyebabkan notifikasi tertentu. Hal ini sering digunakan dalam analisis penyebab utama untuk mengidentifikasi apa yang terjadi tepat sebelum deteksi penting.

rule sliding_window_before_example {
meta:
  description = "Identify file modifications occurring in the 5 minutes before a ransomware alert."
  severity = "Critical"

events:
  $file.metadata.event_type = "FILE_MODIFICATION"
  $file.principal.hostname = $host

  $alert.metadata.event_type = "ANTIVIRUS_DETECTION"
  $alert.metadata.product_name = "Premium_AV"
  $alert.principal.hostname = $host

match:
  // $alert is the pivot; the 5-minute window ends at the $alert timestamp
  $host over 5m before $alert

condition:
  $file and $alert
}

Peringatan: Jendela geser dapat memperlambat performa secara signifikan. Gunakan hanya jika urutan peristiwa sangat diperlukan (misalnya, jika satu peristiwa harus terjadi dalam waktu lima menit setelah peristiwa lain).

Performa dan praktik terbaik

Jendela geser memerlukan daya pemrosesan yang lebih besar daripada jendela standar (hop) karena dihitung untuk setiap kemunculan peristiwa pivot, dan dapat menyebabkan performa yang lebih lambat.

Ikuti panduan berikut untuk performa optimal dalam aturan, penelusuran, dan dasbor:

• Prioritaskan periode lompatan: Gunakan periode lompatan default kecuali jika urutan peristiwa tertentu (pesanan A lalu pesanan B) diperlukan untuk logika deteksi. Gunakan jendela geser hanya jika pengurutan peristiwa sangat penting atau saat Anda mencari peristiwa yang hilang.

• Gunakan filter stempel waktu untuk performa: Jika Anda hanya perlu memastikan satu peristiwa terjadi setelah peristiwa lain, perbandingan stempel waktu di bagian events atau condition sering kali lebih efisien daripada jendela geser, misalnya:

$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds

• Desain multi-peristiwa: Hindari penggunaan jendela geser untuk kueri peristiwa tunggal. Jendela geser dirancang untuk korelasi multi-peristiwa. Untuk logika satu peristiwa, panduan berikut berlaku:

  • Gunakan beberapa variabel peristiwa dan perbarui bagian condition.
  • Hapus bagian match sepenuhnya jika korelasi tidak diperlukan.
  • Atau, pertimbangkan untuk menambahkan filter stempel waktu, bukan menggunakan jendela geser, misalnya:
    $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds

Memahami batas temporal

Bagian match membagi peristiwa ke dalam grup berdasarkan kunci pengelompokan Anda. Durasi yang ditentukan menentukan batas temporal untuk setiap grup:

• Pencantuman: Hanya peristiwa dalam periode yang diteruskan ke evaluasi condition untuk kecocokan tertentu tersebut.
• Pengecualian: Peristiwa di luar periode akan diabaikan untuk grup kecocokan tertentu tersebut, sehingga mencegah peristiwa yang tidak terkait memicu positif palsu.

Nilai nol di bagian match

Google SecOps secara implisit memfilter nilai nol untuk semua placeholder yang digunakan di bagian match ("" untuk string, 0 untuk angka, false untuk boolean, nilai di posisi 0 untuk jenis yang di-enum).

Contoh: Mengecualikan nilai nol

Contoh berikut mengilustrasikan kueri yang memfilter nilai nol.

rule ZeroValuePlaceholderExample {

events:
  // Because $host is used in the match section, the query behaves
  // as if the following predicate was added to the events section:
  // $host != ""
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e
}

Namun, jika placeholder ditetapkan ke fungsi, kueri tidak secara implisit memfilter nilai nol placeholder yang digunakan di bagian match.

Untuk menonaktifkan pemfilteran implisit nilai nol, Anda dapat menggunakan opsi allow_zero_values di bagian opsi. Opsi allow_zero_values hanya tersedia di Aturan.

Contoh: Izinkan nilai nol

Contoh berikut menggambarkan kueri yang tidak secara implisit memfilter nilai nol placeholder yang digunakan di bagian match:

rule AllowZeroValuesExample {

events:
  // Because allow_zero_values is set to true, there is no implicit filtering
  // of zero values for $host.
  $host = $e.principal.hostname

  // Because $otherPlaceholder was not used in the match,
  // there is no implicit filtering of zero values for $otherPlaceholder.
  $otherPlaceholder = $e.principal.ip

match:
  $host over 5m

condition:
  $e

options:
  allow_zero_values = true
}

Langkah berikutnya

Pelajari referensi berikut untuk melanjutkan logika YARA-L Anda atau mempelajari lebih lanjut fungsi kueri lanjutan:

Sintaksis dan logika

• Sintaksis bagian outcome
• Sintaksis bagian condition
• Sintaksis bagian options

Referensi dan contoh

• Ekspresi, operator, dan konstruksi yang digunakan di YARA-L 2.0
• Fungsi di YARA-L 2.0
• Membangun aturan deteksi komposit
• Contoh: Kueri YARA-L 2.0

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