Sintaksis bahasa YARA-L 2.0

Didukung di:

Google SecOps SIEM

Bagian ini menjelaskan elemen utama sintaksis YARA-L. Lihat juga Ringkasan bahasa YARA-L 2.0.

Struktur aturan

Untuk YARA-L 2.0, Anda harus menentukan deklarasi, definisi, dan penggunaan variabel dalam urutan berikut:

1. meta
2. acara
3. match (opsional)
4. outcome (opsional)
5. kondisi
6. options (opsional)

Catatan: Jika Anda menghilangkan bagian match opsional, aturan dapat cocok dengan satu peristiwa.

Berikut ini ilustrasi struktur umum aturan:

rule <rule Name>
{
    meta:
    // Stores arbitrary key-value pairs of rule details, such as who wrote
    // it, what it detects on, version control, etc.

  events:
    // Conditions to filter events and the relationship between events.

  match:
    // Values to return when matches are found.

  outcome:
    // Additional information extracted from each detection.

  condition:
    // Condition to check events and the variables used to find matches.

  options:
    // Options to turn on or off while executing this rule.
}

Sintaksis bagian meta

Bagian meta terdiri dari beberapa baris, dengan setiap baris menentukan pasangan nilai kunci. Bagian kunci harus berupa string tanpa tanda kutip, dan bagian nilai harus berupa string dengan tanda kutip:

<key> = "<value>"

Berikut adalah contoh baris bagian meta yang valid:

meta:
    author = "Google"
    severity = "HIGH"

Sintaksis bagian Peristiwa

Di bagian events, cantumkan predikat untuk menentukan hal berikut:

• Deklarasi variabel
• Filter variabel peristiwa
• Penggabungan variabel peristiwa

Deklarasi variabel

Untuk deklarasi variabel, gunakan sintaksis berikut:

• <EVENT_FIELD> = <VAR>
• <VAR> = <EVENT_FIELD>

Keduanya setara, seperti ditunjukkan dalam contoh berikut:

• $e.source.hostname = $hostname
• $userid = $e.principal.user.userid

Deklarasi ini menunjukkan bahwa variabel ini mewakili kolom yang ditentukan untuk variabel peristiwa. Jika kolom peristiwa adalah kolom berulang, variabel kecocokan dapat mewakili nilai apa pun dalam array. Anda juga dapat menetapkan beberapa kolom peristiwa ke satu pencocokan atau variabel placeholder. Ini adalah kondisi join transitif.

Misalnya:

• $e1.source.ip = $ip
• $e2.target.ip = $ip

Setara dengan:

• $e1.source.ip = $ip
• $e1.source.ip = $e2.target.ip

Saat digunakan, variabel harus dideklarasikan melalui deklarasi variabel. Jika digunakan tanpa deklarasi, variabel akan dianggap sebagai error kompilasi.

Filter variabel peristiwa

Ekspresi boolean yang bertindak pada satu variabel peristiwa dianggap sebagai filter.

Penggabungan variabel peristiwa

Semua variabel peristiwa yang digunakan dalam aturan harus digabungkan dengan setiap variabel peristiwa lainnya dengan salah satu cara berikut:

• Secara langsung melalui perbandingan kesetaraan antara kolom peristiwa dari dua variabel peristiwa yang digabungkan, misalnya: $e1.field = $e2.field. Ekspresi tidak boleh menyertakan aritmetika.

• Secara tidak langsung melalui join transitif yang hanya melibatkan kolom peristiwa (lihat deklarasi variabel untuk mengetahui definisi "join transitif"). Ekspresi tidak boleh menyertakan aritmetika.

Misalnya, dengan asumsi $e1, $e2, dan $e3 digunakan dalam aturan, bagian events berikut valid.

events:
  $e1.principal.hostname = $e2.src.hostname // $e1 joins with $e2
  $e2.principal.ip = $e3.src.ip // $e2 joins with $e3

events:
  // $e1 joins with $e2 via function to event comparison
  re.capture($e1.src.hostname, ".*") = $e2.target.hostname

events:
  // $e1 joins with $e2 via an `or` expression
  $e1.principal.hostname = $e2.src.hostname
  or $e1.principal.hostname = $e2.target.hostname
  or $e1.principal.hostname = $e2.principal.hostname

events:
  // all of $e1, $e2 and $e3 are transitively joined via the placeholder variable $ip
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = $ip

events:
  // $e1 and $e2 are transitively joined via function to event comparison
  re.capture($e2.principal.application, ".*") = $app
  $e1.principal.hostname = $app

Catatan: Jika satu-satunya kondisi join Anda adalah rantai or, perbandingan fungsi dengan peristiwa, atau kombinasi keduanya, aturan tersebut mungkin berperforma buruk.

Namun, berikut adalah contoh bagian events yang tidak valid.

events:
  // Event to arithmetic comparison is an invalid join condition for $e1 and $e2.
  $e1.principal.port = $e2.src.port + 1

events:
  $e1.src.ip = $ip
  $e2.target.ip = $ip
  $e3.about.ip = "192.1.2.0" //$e3 is not joined with $e1 or $e2.

events:
  $e1.src.port = $port

  // Arithmetic to placeholder comparison is an invalid transitive join condition.
  $e2.principal.port + 800 = $port

Sintaksis bagian Pencocokan

Di bagian match, cantumkan variabel pencocokan untuk peristiwa grup sebelum memeriksa kondisi pencocokan. Kolom tersebut ditampilkan dengan setiap kecocokan.

• Tentukan apa yang diwakili oleh setiap variabel pencocokan di bagian events.
• Tentukan durasi waktu yang akan digunakan untuk mengaitkan peristiwa setelah kata kunci over. Peristiwa di luar durasi waktu akan diabaikan.

• Gunakan sintaksis berikut untuk menentukan durasi waktu: <number><m/h/d>

  Dengan m/h/d masing-masing berarti menit, jam, dan hari.

• Waktu minimum yang dapat Anda tentukan adalah 1 menit.

• Waktu maksimum yang dapat Anda tentukan adalah 48 jam.

Berikut adalah contoh match yang valid:

$var1, $var2 over 5m

Pernyataan ini menampilkan $var1 dan $var2 (ditentukan di bagian events) saat aturan menemukan kecocokan. Waktu yang ditentukan adalah 5 menit. Peristiwa yang berjarak lebih dari 5 menit tidak berkorelasi sehingga diabaikan oleh aturan.

Berikut adalah contoh lain bagian match yang valid:

$user over 1h

Pernyataan ini menampilkan $user saat aturan menemukan kecocokan. Periode waktu yang ditentukan adalah 1 jam. Peristiwa yang berjarak lebih dari satu jam tidak berkorelasi. Aturan tidak menganggapnya sebagai deteksi.

Berikut adalah contoh lain bagian match yang valid:

$source_ip, $target_ip, $hostname over 2m

Pernyataan ini menampilkan $source_ip, $target_ip, dan $hostname saat aturan menemukan kecocokan. Jangka waktu yang ditentukan adalah 2 menit. Peristiwa yang berjarak lebih dari 2 menit tidak berkorelasi. Aturan tidak menganggapnya sebagai deteksi.

Contoh berikut mengilustrasikan bagian match yang tidak valid:

• var1, var2 over 5m // invalid variable name
• $user 1h // missing keyword

Penanganan nilai nol di bagian pencocokan

Mesin Aturan secara implisit memfilter nilai nol untuk semua placeholder yang digunakan di bagian pencocokan ("" untuk string, 0 untuk angka, false untuk boolean, nilai di posisi 0 untuk jenis yang dihitung). Contoh berikut mengilustrasikan aturan yang memfilter nilai nol.

rule ZeroValuePlaceholderExample {
  meta:
  events:
    // Because $host is used in the match section, the rule 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 section,
    // 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, aturan tidak akan secara implisit memfilter nilai nol placeholder yang digunakan di bagian pencocokan. Contoh berikut mengilustrasikan aturan yang memfilter nilai nol:

rule ZeroValueFunctionPlaceholder {
  meta:
  events:
    // Even though $ph is used in the match section, there is no
    // implicit filtering of zero values for $ph, because $ph is assigned to a function.
    $ph = re.capture($e.principal.hostname, "some-regex")

  match:
    $ph over 5m

  condition:
    $e
}

Untuk menonaktifkan pemfilteran implisit nilai nol, Anda dapat menggunakan opsi allow_zero_values di bagian opsi.

Periode hopping

Secara default, aturan YARA-L 2.0 dengan bagian kecocokan dievaluasi menggunakan periode hop. Rentang waktu eksekusi aturan dibagi menjadi serangkaian jendela hop yang tumpang-tindih, masing-masing dengan durasi yang ditentukan di bagian match. Peristiwa kemudian dikorelasikan dalam setiap periode hop.

Misalnya, untuk aturan yang dijalankan selama rentang waktu [1:00, 2:00], dengan bagian match di atas 30m, kemungkinan kumpulan periode hop tumpang-tindih yang dapat dihasilkan adalah [1:00, 1:30], [1:03, 1:33], dan [1:06, 1:36]. Periode ini digunakan untuk mengaitkan beberapa peristiwa.

Jendela geser

Menggunakan periode hop bukanlah cara yang efektif untuk menelusuri peristiwa yang terjadi dalam urutan tertentu (misalnya, e1 terjadi hingga 2 menit setelah e2). Kejadian peristiwa e1 dan kejadian peristiwa e2 hanya berkorelasi jika keduanya berada dalam periode hop yang sama yang dihasilkan.

Cara yang lebih efektif untuk menelusuri urutan peristiwa tersebut adalah dengan menggunakan jendela geser. Periode geser dengan durasi yang ditentukan di bagian match dihasilkan saat dimulai atau diakhiri dengan variabel peristiwa pivot yang ditentukan. Peristiwa kemudian dikorelasi dalam setiap periode geser. Hal ini memungkinkan penelusuran peristiwa yang terjadi dalam urutan tertentu (misalnya, e1 terjadi dalam waktu 2 menit setelah e2). Kejadian peristiwa e1 dan kejadian peristiwa e2 berkorelasi jika peristiwa e1 terjadi dalam durasi periode geser setelah peristiwa e2.

Tentukan periode geser di bagian match aturan sebagai berikut:

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

Variabel peristiwa pivot adalah variabel peristiwa yang menjadi dasar jendela geser. Jika Anda menggunakan kata kunci before, jendela geser akan dibuat, yang diakhiri dengan setiap kemunculan peristiwa pivot. Jika kata kunci after digunakan, jendela geser akan dibuat mulai dari setiap kemunculan peristiwa pivot.

Berikut adalah contoh penggunaan jendela geser yang valid:

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

Lihat contoh aturan jendela geser.

Catatan: Penggunaan jendela geser, bukan jendela hop, diketahui menghasilkan performa yang lebih lambat. Google merekomendasikan penggunaan periode geser hanya untuk kasus tertentu, seperti saat urutan peristiwa benar-benar diperlukan atau saat menelusuri ketidakadaan peristiwa.

Google merekomendasikan untuk tidak menggunakan periode geser untuk aturan peristiwa tunggal, karena periode geser dirancang untuk mendeteksi beberapa peristiwa. Jika salah satu aturan Anda termasuk dalam kategori ini, Google merekomendasikan salah satu solusi berikut:

• Konversikan aturan untuk menggunakan beberapa variabel peristiwa, dan perbarui bagian kondisi jika aturan memerlukan lebih dari satu kemunculan peristiwa.
  • Jika perlu, pertimbangkan untuk menambahkan filter stempel waktu, bukan menggunakan periode geser. Contoh, $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
• Lepaskan jendela geser.

Sintaksis bagian hasil

Di bagian outcome, Anda dapat menentukan hingga 20 variabel hasil, dengan nama arbitrer. Hasil ini akan disimpan dalam deteksi yang dihasilkan oleh aturan. Setiap deteksi mungkin memiliki nilai yang berbeda untuk hasilnya.

Nama hasil, $risk_score, bersifat khusus. Secara opsional, Anda dapat menentukan hasil dengan nama ini, dan jika melakukannya, hasil tersebut harus berupa jenis bilangan bulat atau float. Jika diisi, risk_score akan ditampilkan di tampilan Enterprise Insights untuk notifikasi yang berasal dari deteksi aturan.

Jika Anda tidak menyertakan variabel $risk_score di bagian hasil aturan, salah satu nilai default berikut akan ditetapkan:

• Jika aturan dikonfigurasi untuk membuat pemberitahuan, $risk_score akan ditetapkan ke 40.
• Jika aturan tidak dikonfigurasi untuk membuat pemberitahuan, $risk_score akan ditetapkan ke 15.

Nilai $risk_score disimpan di kolom UDM security_result.risk_score.

Jenis data variabel hasil

Setiap variabel hasil dapat memiliki jenis data yang berbeda, yang ditentukan oleh ekspresi yang digunakan untuk menghitungnya. Kami mendukung jenis data hasil berikut:

• bilangan bulat
• float
• string
• daftar bilangan bulat
• daftar float
• daftar string

Logika kondisional

Anda dapat menggunakan logika bersyarat untuk menghitung nilai hasil. Kondisional ditentukan menggunakan pola sintaksis berikut:

if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)

Anda dapat membaca ekspresi kondisional sebagai "if BOOL_CLAUSE is true, then return THEN_CLAUSE, else return ELSE_CLAUSE".

BOOL_CLAUSE harus dievaluasi ke nilai boolean. Ekspresi BOOL_CLAUSE menggunakan format yang mirip dengan ekspresi di bagian events. Misalnya, cache dapat berisi:

• Nama kolom UDM dengan operator perbandingan, misalnya:

  if($context.graph.entity.user.title = "Vendor", 100, 0)

• variabel placeholder yang ditentukan di bagian events, misalnya:

  if($severity = "HIGH", 100, 0)

• variabel hasil lain yang ditentukan di bagian outcome, misalnya:

  if($risk_score > 20, "HIGH", "LOW")

• fungsi yang menampilkan boolean, misalnya:

  if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)

• mencari di daftar referensi, misalnya:

  if($u.principal.hostname in %my_reference_list_name, 100, 0)

• perbandingan agregasi, misalnya:

  if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)

THEN_CLAUSE dan ELSE_CLAUSE harus memiliki jenis data yang sama. Kami mendukung bilangan bulat, bilangan mengambang, dan string.

Anda dapat menghilangkan ELSE_CLAUSE jika jenis datanya adalah bilangan bulat atau float. Jika dihilangkan, ELSE_CLAUSE akan bernilai 0. Contoh:

`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`

Anda harus memberikan ELSE_CLAUSE jika jenis datanya adalah string atau jika THEN_CLAUSE adalah variabel placeholder atau variabel hasil.

Operasi matematika

Anda dapat menggunakan operasi matematika untuk menghitung jenis data bilangan bulat atau float di bagian outcome dan events aturan. Google Security Operations mendukung penambahan, pengurangan, perkalian, pembagian, dan modulus sebagai operator tingkat teratas dalam komputasi.

Cuplikan berikut adalah contoh komputasi di bagian outcome:

outcome:
  $risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))

Operasi matematika diizinkan pada jenis operand berikut selama setiap operand dan seluruh ekspresi aritmetika digabungkan dengan benar (Lihat Agregasi):

• Kolom peristiwa numerik
• Variabel placeholder numerik yang ditentukan di bagian events
• Variabel hasil numerik yang ditentukan di bagian outcome
• Fungsi yang menampilkan int atau float
• Agregasi yang menampilkan int atau float

Modulus tidak diizinkan pada float.

Variabel placeholder dalam hasil

Saat menghitung variabel hasil, Anda dapat menggunakan variabel placeholder yang ditentukan di bagian peristiwa dalam aturan. Dalam contoh ini, asumsikan bahwa $email_sent_bytes ditentukan di bagian peristiwa aturan:

Contoh peristiwa tunggal:

// No match section, so this is a single-event rule.

outcome:
  // Use placeholder directly as an outcome value.
  $my_outcome = $email_sent_bytes

  // Use placeholder in a conditional.
  $other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")

condition:
  $e

Contoh multi-peristiwa:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Use placeholder directly in an aggregation function.
  $max_email_size = max($email_sent_bytes)

  // Use placeholder in a mathematical computation.
  $total_bytes_exfiltrated = sum(
    1024
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Variabel hasil dalam ekspresi penetapan hasil

Variabel hasil dapat digunakan untuk memperoleh variabel hasil lainnya, mirip dengan variabel placeholder yang ditentukan di bagian events. Anda dapat merujuk ke variabel hasil dalam penetapan variabel hasil lain dengan token $ yang diikuti oleh nama variabel. Variabel hasil harus ditentukan sebelum dapat dirujuk dalam teks aturan. Saat digunakan dalam ekspresi penetapan, variabel hasil tidak boleh digabungkan (Lihat Agregasi).

Dalam contoh berikut, variabel hasil $risk_score memperoleh nilainya dari variabel hasil $event_count:

Contoh multi-peristiwa:

match:
  // This is a multi event rule with a match section.
  $hostname over 5m

outcome:
  // Aggregates all timestamp on login events in the 5 minute match window.
  $event_count = count($login.metadata.event_timestamp.seconds)
  
  // $event_count cannot be aggregated again.
  $risk_score = if($event_count > 5, "SEVERE", "MODERATE")

  // This is the equivalent of the 2 outcomes above combined.
  $risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")

condition:
  $e

Variabel hasil dapat digunakan dalam jenis ekspresi apa pun di sisi kanan penetapan hasil, kecuali dalam ekspresi berikut:

• Agregasi
• Panggilan fungsi Arrays.length()
• Dengan pengubah any atau all

Agregasi

Kolom peristiwa berulang adalah nilai non-skalar. Artinya, satu variabel mengarah ke beberapa nilai. Misalnya, variabel kolom peristiwa $e.target.ip adalah kolom berulang dan dapat memiliki nol, satu, atau banyak nilai IP. Ini adalah nilai non-skalar. Sedangkan variabel kolom peristiwa $e.principal.hostname bukan kolom berulang dan hanya memiliki 1 nilai (yaitu nilai skalar).

Demikian pula, kolom peristiwa yang tidak berulang dan kolom peristiwa berulang yang digunakan di bagian hasil aturan dengan periode pencocokan adalah nilai non-skalar. Misalnya, aturan berikut mengelompokkan peristiwa menggunakan bagian kecocokan dan merujuk ke kolom peristiwa yang tidak berulang di bagian hasil:

rule OutcomeAndMatchWindow{
  ...
  match:
    $userid over 5m
  outcome:
    $hostnames = array($e.principal.hostname)
  ...
}

Setiap periode 5 menit saat aturan dieksekusi mungkin berisi nol, satu, atau banyak peristiwa. Bagian hasil beroperasi pada semua peristiwa dalam jendela kecocokan. Setiap variabel kolom peristiwa yang dirujuk dalam bagian hasil dapat mengarah ke nol, satu, atau banyak nilai kolom pada setiap peristiwa dalam periode pencocokan. Dalam aturan sebelumnya, jika periode 5 menit berisi 5 peristiwa $e, $e.principal.hostname di bagian hasil akan mengarah ke 5 nama host yang berbeda. Dengan demikian, variabel kolom peristiwa $e.principal.hostname adalah nilai non-skalar di bagian hasil aturan ini.

Karena variabel hasil harus selalu menghasilkan satu nilai skalar, nilai non-skalar apa pun yang menjadi dasar penetapan hasil harus digabungkan untuk menghasilkan satu nilai skalar. Di bagian hasil, berikut adalah nilai non-skalar dan harus digabungkan:

• Kolom peristiwa (berulang atau tidak berulang) saat aturan menggunakan bagian kecocokan
• Placeholder peristiwa (diulang atau tidak diulang) saat aturan menggunakan bagian pencocokan
• Kolom peristiwa berulang saat aturan tidak menggunakan bagian kecocokan
• Placeholder peristiwa berulang saat aturan tidak menggunakan bagian kecocokan

Kolom peristiwa skalar, placeholder peristiwa skalar, dan konstanta dapat digabungkan dalam agregasi dalam aturan yang tidak menggunakan bagian kecocokan. Namun, sebagian besar agregasi akan menghasilkan nilai yang digabungkan sehingga tidak diperlukan. Pengecualian adalah agregasi array() yang dapat digunakan untuk mengonversi nilai skalar menjadi array.

Variabel hasil diperlakukan seperti agregasi: variabel tersebut tidak boleh digabungkan ulang saat dirujuk dalam penetapan hasil lain.

Anda dapat menggunakan fungsi agregasi berikut:

• max(): menampilkan nilai maksimum dari semua kemungkinan nilai. Hanya berfungsi dengan bilangan bulat dan bilangan pecahan.
• min(): menampilkan nilai minimum dari semua kemungkinan nilai. Hanya berfungsi dengan bilangan bulat dan bilangan pecahan.
• sum(): menampilkan jumlah dari semua kemungkinan nilai. Hanya berfungsi dengan bilangan bulat dan bilangan pecahan.
• count_distinct(): mengumpulkan semua kemungkinan nilai, lalu menghasilkan jumlah yang berbeda dari kemungkinan nilai.
• count(): berperilaku seperti count_distinct(), tetapi menampilkan jumlah kemungkinan nilai yang tidak berbeda.
• array_distinct(): mengumpulkan semua kemungkinan nilai yang berbeda, lalu menghasilkan daftar nilai ini. Tindakan ini akan memotong daftar nilai yang berbeda menjadi 25 elemen acak. Penghapusan duplikat untuk mendapatkan daftar yang berbeda diterapkan terlebih dahulu, lalu pemotongan diterapkan.
• array(): berperilaku seperti array_distinct(), tetapi menampilkan daftar nilai yang tidak berbeda. Fungsi ini juga memotong daftar nilai menjadi 25 elemen acak.
• period_start_for_max(): awal jangka waktu saat maksimum nilai yang tercantum terjadi.
• period_start_for_min(): awal jangka waktu saat nilai minimum yang tercantum terjadi.

Fungsi gabungan penting jika aturan menyertakan bagian condition yang menentukan bahwa beberapa peristiwa harus ada, karena fungsi gabungan akan beroperasi pada semua peristiwa yang menghasilkan deteksi.

Misalnya, jika bagian outcome dan condition Anda berisi:

outcome:
  $asset_id_count = count($event.principal.asset_id)
  $asset_id_distinct_count = count_distinct($event.principal.asset_id)

  $asset_id_list = array($event.principal.asset_id)
  $asset_id_distinct_list = array_distinct($event.principal.asset_id)

condition:
  #event > 1

Karena bagian kondisi mengharuskan adanya lebih dari satu event untuk setiap deteksi, fungsi gabungan akan beroperasi pada beberapa peristiwa. Misalkan peristiwa berikut menghasilkan satu deteksi:

event:
  // UDM event 1
  asset_id="asset-a"

event:
  // UDM event 2
  asset_id="asset-b"

event:
  // UDM event 3
  asset_id="asset-b"

Kemudian, nilai hasil Anda akan menjadi:

• $asset_id_count = 3
• $asset_id_distinct_count = 2
• $asset_id_list = ["asset-a", "asset-b", "asset-b"]
• $asset_id_distinct_list = ["asset-a", "asset-b"]

Hal-hal yang perlu diketahui saat menggunakan bagian hasil:

Catatan dan batasan lainnya:

• Bagian outcome tidak dapat mereferensikan variabel placeholder baru yang belum ditentukan di bagian events atau di bagian outcome.
• Bagian outcome tidak dapat menggunakan variabel peristiwa yang belum ditentukan di bagian events.
• Bagian outcome dapat menggunakan kolom peristiwa yang tidak digunakan di bagian events, mengingat variabel peristiwa yang menjadi milik kolom peristiwa sudah ditentukan di bagian events.
• Bagian outcome hanya dapat menghubungkan variabel peristiwa yang telah dihubungkan di bagian events. Korelasi terjadi saat dua kolom peristiwa dari variabel peristiwa yang berbeda disamakan.

Anda dapat menemukan contoh yang menggunakan bagian hasil di Ringkasan YARA-L 2.0. Lihat Membuat analisis kontekstual untuk mengetahui detail penghapusan duplikat deteksi dengan bagian hasil.

Sintaksis bagian Condition

• menentukan kondisi kecocokan pada peristiwa dan placeholder yang ditentukan di bagian events. Lihat bagian berikut, Kondisional peristiwa dan placeholder, untuk mengetahui detail selengkapnya.
• (opsional) gunakan kata kunci and untuk menentukan kondisi kecocokan menggunakan variabel hasil yang ditentukan di bagian outcome. Lihat bagian berikut, Kondisional hasil, untuk mengetahui detail selengkapnya.

Menghitung karakter

Karakter # adalah karakter khusus di bagian condition. Jika digunakan sebelum nama variabel placeholder atau peristiwa, variabel ini mewakili jumlah peristiwa atau nilai yang berbeda yang memenuhi semua kondisi bagian events.

Misalnya, #c > 1 berarti variabel c harus muncul lebih dari 1 kali.

Karakter nilai

Karakter $ adalah karakter khusus di bagian condition. Jika digunakan sebelum nama variabel hasil, variabel ini akan mewakili nilai hasil tersebut.

Jika digunakan sebelum nama variabel placeholder atau peristiwa (misalnya, $event), variabel ini akan mewakili #event > 0.

Kondisional peristiwa dan placeholder

Cantumkan predikat kondisi untuk peristiwa dan variabel placeholder di sini, yang digabungkan dengan kata kunci and atau or. Kata kunci and dapat digunakan di antara kondisi apa pun, tetapi kata kunci or hanya dapat digunakan jika aturan hanya memiliki satu variabel peristiwa.

Contoh valid penggunaan or di antara dua placeholder pada peristiwa yang sama:

rule ValidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"

      // Note that all placeholders use the same event variable.
      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.
      $ph2 = $e.principal.ip  // Define a second placeholder variable to put in condition section.
      $ph3 = $e.principal.hostname  // Define a third placeholder variable to put in condition section.

  match:
    $ph over 5m

  condition:
    $ph2 or $ph3
}

Contoh penggunaan or yang tidak valid antara dua kondisi pada peristiwa yang berbeda:

rule InvalidConditionOr {
  meta:
  events:
      $e.metadata.event_type = "NETWORK_CONNECTION"
      $e2.graph.metadata.entity_type = "FILE"
      $e2.graph.entity.hostname  = $e.principal.hostname

      $ph = $e.principal.user.userid  // Define a placeholder variable to put in match section.

  match:
    $ph over 5m

  condition:
    $e or $e2 // This line will cause an error because there is an or between events.
}

Catatan: Jangan gunakan kata kunci not dalam kondisional peristiwa dan placeholder.

Kondisi Terbatas dan Tidak Terbatas

Kondisi berikut adalah kondisi terbatas. Peristiwa ini memaksa variabel peristiwa terkait ada, yang berarti setidaknya satu kemunculan peristiwa harus muncul dalam deteksi apa pun.

• $var // equivalent to #var > 0
• #var > n // where n >= 0
• #var >= m // where m > 0

Kondisi berikut adalah kondisi tanpa batas. Fungsi ini memungkinkan variabel peristiwa terkait tidak ada, yang berarti mungkin tidak ada kemunculan peristiwa yang muncul dalam deteksi dan referensi apa pun ke kolom pada variabel peristiwa akan menghasilkan nilai nol. Kondisi tanpa batas dapat digunakan untuk mendeteksi tidak adanya peristiwa selama jangka waktu tertentu. Misalnya, peristiwa ancaman tanpa peristiwa mitigasi dalam jangka waktu 10 menit. Aturan yang menggunakan kondisi tanpa batas disebut aturan non-eksistensi.

• !$var // equivalent to #var = 0
• #var >= 0
• #var < n // where n > 0
• #var <= m // where m >= 0

Catatan: Untuk aturan tidak ada, mesin deteksi menambahkan penundaan 1 jam ke latensi yang diharapkan (berdasarkan frekuensi pengoperasian aturan) untuk memungkinkan data yang tiba terlambat.

Persyaratan untuk ketidakadaan

Agar dapat dikompilasi, aturan dengan non-eksistensi harus memenuhi persyaratan berikut:

1. Setidaknya satu peristiwa UDM harus memiliki kondisi terbatas (yaitu, setidaknya satu peristiwa UDM harus ada).
2. Jika memiliki kondisi yang tidak terbatas, placeholder harus dikaitkan dengan setidaknya satu peristiwa UDM yang dibatasi.
3. Jika memiliki kondisi yang tidak terbatas, entity harus dikaitkan dengan setidaknya satu peristiwa UDM yang dibatasi.

Pertimbangkan aturan berikut dengan bagian kondisi dihilangkan:

rule NonexistenceExample {
  meta:
  events:
      $u1.metadata.event_type = "NETWORK_CONNECTION" // $u1 is a UDM event.
      $u2.metadata.event_type = "NETWORK_CONNECTION" // $u2 is a UDM event.
      $e1.graph.metadata.entity_type = "FILE"        // $e1 is an Entity.
      $e2.graph.metadata.entity_type = "FILE"        // $e2 is an Entity.

      $user = $u1.principal.user.userid // Match variable is required for Multi-Event Rule.

      // Placeholder Associations:
      //   u1        u2 
      //   |  \    /
      // port   ip
      //   |       \
      //   e1        e2
      $u1.target.port = $port
      $e1.graph.entity.port = $port
      $u1.principal.ip = $ip
      $u2.target.ip = $ip
      $e2.graph.entity.ip = $ip

      // UDM-Entity Associations:
      // u1 - u2
      // |  \  |
      // e1   e2
      $u1.metadata.event_type = $u2.metadata.event_type
      $e1.graph.entity.hostname = $u1.principal.hostname
      $e2.graph.entity.hostname = $u1.target.hostname
      $e2.graph.entity.hostname = $u2.principal.hostname

  match:
    $user over 5m

  condition:
      <condition_section>
}

Berikut adalah contoh valid untuk <condition_section>:

• $u1 and !$u2 and $e1 and $e2
  • Semua peristiwa dan entitas UDM ada di bagian kondisi.
  • Setidaknya satu peristiwa UDM dibatasi.
• $u1 and !$u2 and $e1 and !$e2
  • $e2 tidak dibatasi, yang diizinkan karena terkait dengan $u1, yang dibatasi. Jika $e2 tidak dikaitkan dengan $u1, nilai ini akan tidak valid.
• #port > 50 and #ip = 0
  • Tidak ada peristiwa dan entitas UDM di bagian kondisi; namun, placeholder yang ada mencakup semua peristiwa dan entitas UDM.
  • $ip ditetapkan ke $u1 dan $u2, dan #ip = 0 adalah kondisi yang tidak terbatas. Namun, kondisi terbatas lebih kuat daripada kondisi tidak terbatas. Karena $port ditetapkan ke $u1 dan #port > 50 adalah kondisi yang dibatasi, $u1 masih dibatasi.

Berikut adalah contoh tidak valid untuk <condition_section>:

• $u1 and $e1
  • Setiap peristiwa dan entitas UDM yang muncul di Bagian Peristiwa harus muncul di Bagian Kondisi (atau memiliki placeholder yang ditetapkan yang muncul di Bagian Kondisi).
• $u1, $u2, $e1, $u2, #port > 50
  • Tanda koma tidak diizinkan sebagai pemisah kondisi.
• !$u1 and !$u2 and $e1 and $e2
  • Melanggar persyaratan pertama bahwa setidaknya satu peristiwa UDM dibatasi.
• ($u1 or #port < 50) and $u2 and $e1 and $e2
  • Kata kunci or tidak didukung dengan kondisi yang tidak terbatas.
• ($u1 or $u2) and $e1 and $e2
  • Kata kunci or tidak didukung di antara variabel peristiwa yang berbeda.
• not $u1 and $u2 and $e1 and $e2
  • Kata kunci not tidak diizinkan untuk kondisi peristiwa dan placeholder.
• #port < 50 and #ip = 0
  • Placeholder yang ada mencakup semua peristiwa dan entitas UDM; namun, semua kondisi tidak dibatasi. Artinya, tidak ada peristiwa UDM yang dibatasi, sehingga aturan gagal dikompilasi.

Catatan: Jangan gunakan variabel match di bagian condition. Ini adalah error semantik karena peristiwa dikelompokkan berdasarkan nilai variabel match.

Catatan: Jangan hanya menentukan kondisi tanpa batas pada semua variabel event yang ditetapkan ke variabel match. Ini adalah error semantik. Agar nilai variabel match ditampilkan, setidaknya harus ada satu peristiwa yang berisi nilai tersebut.

Catatan: Jika menggunakan periode geser, variabel peristiwa pivot harus terlibat dalam setidaknya satu kondisi terbatas.

Kondisional hasil

Cantumkan predikat kondisi untuk variabel hasil di sini, yang digabungkan dengan kata kunci and atau or, atau didahului dengan kata kunci not.

Tentukan kondisional hasil secara berbeda bergantung pada jenis variabel hasil:

• integer: bandingkan dengan literal bilangan bulat dengan operator =, >, >=, <, <=, !=, misalnya:

  $risk_score > 10

• float: membandingkan dengan literal float menggunakan operator =, >, >=, <, <=, !=, misalnya:

  $risk_score <= 5.5

• string: bandingkan dengan literal string dengan = atau !=, misalnya:

  $severity = "HIGH"

• daftar bilangan bulat atau array: tentukan kondisi menggunakan fungsi arrays.contains, misalnya:

  arrays.contains($event_ids, "id_1234")

Catatan: Jika menggunakan kata kunci or di dalam subbagian <event/placeholder conditionals>, Anda harus mengapit seluruh subbagian tersebut dengan tanda kurung. Misalnya, berikut ini valid: ($e1 or $e2) and $outcome > 0.

Klasifikasi aturan

Menentukan kondisi hasil dalam aturan yang memiliki bagian kecocokan berarti aturan tersebut akan diklasifikasikan sebagai aturan multi-peristiwa untuk kuota aturan. Lihat aturan peristiwa tunggal dan aturan multi-peristiwa untuk mengetahui informasi selengkapnya tentang klasifikasi peristiwa tunggal dan multi-peristiwa.

Sintaksis bagian Opsi

Di bagian options, Anda dapat menentukan opsi untuk aturan. Berikut adalah contoh cara menentukan bagian opsi:

rule RuleOptionsExample {
  // Other rule sections

  options:
    allow_zero_values = true
}

Anda dapat menentukan opsi menggunakan sintaksis key = value, dengan key harus berupa nama opsi yang telah ditentukan sebelumnya dan value harus berupa nilai yang valid untuk opsi, seperti yang ditentukan untuk opsi berikut:

allow_zero_values

Nilai yang valid untuk opsi ini adalah true dan false, yang menentukan apakah opsi ini diaktifkan atau tidak. Nilai defaultnya adalah false. Opsi ini dinonaktifkan jika tidak ditentukan dalam aturan.

Untuk mengaktifkan setelan ini, tambahkan kode berikut ke bagian opsi aturan Anda: allow_zero_values = true. Tindakan ini akan mencegah aturan memfilter secara implisit nilai nol placeholder yang digunakan di bagian pencocokan, seperti yang dijelaskan dalam penanganan nilai nol di bagian pencocokan.

Ekspresi Boolean

Ekspresi boolean adalah ekspresi dengan jenis boolean.

Perbandingan

Untuk ekspresi biner yang akan digunakan sebagai kondisi, gunakan sintaksis berikut:

• <EXPR> <OP> <EXPR>

Ekspresi dapat berupa kolom peristiwa, variabel, literal, atau ekspresi fungsi.

Contoh:

• $e.source.hostname = "host1234"
• $e.source.port < 1024
• 1024 < $e.source.port
• $e1.source.hostname != $e2.target.hostname
• $e1.metadata.collected_timestamp.seconds > $e2.metadata.collected_timestamp.seconds
• $port >= 25
• $host = $e2.target.hostname
• "google-test" = strings.concat($e.principal.hostname, "-test")
• "[e-mail]" = re.replace($e.network.email.from, "com", "org")

Jika kedua sisinya adalah literal, hal ini dianggap sebagai error kompilasi.

Functions

Beberapa ekspresi fungsi menampilkan nilai boolean, yang dapat digunakan sebagai predikat individual di bagian events. Fungsi tersebut adalah:

• re.regex()
• net.ip_in_range_cidr()

Contoh:

• re.regex($e.principal.hostname, `.*\.google\.com`)
• net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Ekspresi daftar referensi

Anda dapat menggunakan daftar referensi di bagian peristiwa. Lihat bagian Daftar Referensi untuk mengetahui detail selengkapnya.

Ekspresi logika

Anda dapat menggunakan operator and logis dan or logis di bagian events seperti yang ditunjukkan dalam contoh berikut:

• $e.metadata.event_type = "NETWORK_DNS" or $e.metadata.event_type = "NETWORK_DHCP"
• ($e.metadata.event_type = "NETWORK_DNS" and $e.principal.ip = "192.0.2.12") or ($e.metadata.event_type = "NETWORK_DHCP" and $e.principal.mac = "AB:CD:01:10:EF:22")
• not $e.metadata.event_type = "NETWORK_DNS"

Secara default, urutan prioritas dari tertinggi ke terendah adalah not, and, or.

Misalnya, "a or b and c" dievaluasi sebagai "a or (b and c)" saat operator or dan and ditentukan secara eksplisit dalam ekspresi.

Di bagian events, predikat digabungkan menggunakan operator and jika operator tidak ditentukan secara eksplisit.

Urutan evaluasi mungkin berbeda jika operator and tersirat dalam ekspresi.

Misalnya, pertimbangkan ekspresi perbandingan berikut dengan or ditentukan secara eksplisit. Operator and tersirat.

$e1.field = "bat"
or $e1.field = "baz"
$e2.field = "bar"

Contoh ini ditafsirkan sebagai berikut:

($e1.field = "bat" or $e1.field = "baz")
and ($e2.field = "bar")

Karena or ditentukan secara eksplisit, predikat di sekitar or dikelompokkan dan dievaluasi terlebih dahulu. Predikat terakhir, $e2.field = "bar" digabungkan secara implisit menggunakan and. Akibatnya, urutan evaluasi akan berubah.

Catatan: Ada batasan jumlah nilai and dan or yang dapat Anda tentukan untuk satu aturan. Batas ini bervariasi bergantung pada kompleksitas aturan dan kompleksitas data di akun Google Security Operations Anda. Hubungi perwakilan Google Security Operations untuk mendapatkan informasi tentang alternatif untuk jenis aturan ini.

Jenis yang dihitung

Anda dapat menggunakan operator dengan jenis yang dihitung. Operator ini dapat diterapkan ke aturan untuk menyederhanakan dan mengoptimalkan (menggunakan operator, bukan daftar referensi) performa.

Dalam contoh berikut, 'USER_UNCATEGORIZED' dan 'USER_RESOURCE_DELETION' sesuai dengan 15000 dan 15014, sehingga aturan akan mencari semua peristiwa yang tercantum:

$e.metadata.event_type >= "USER_CATEGORIZED" and $e.metadata.event_type <= "USER_RESOURCE_DELETION"

Daftar peristiwa:

• USER_RESOURCE_DELETION
• USER_RESOURCE_UPDATE_CONTENT
• USER_RESOURCE_UPDATE_PERMISSIONS
• USER_STATS
• USER_UNCATEGORIZED

Pengubah Nocase

Jika memiliki ekspresi perbandingan antara nilai string atau ekspresi reguler, Anda dapat menambahkan nocase di akhir ekspresi untuk mengabaikan kapitalisasi.

• $e.principal.hostname != "http-server" nocase
• $e1.principal.hostname = $e2.target.hostname nocase
• $e.principal.hostname = /dns-server-[0-9]+/ nocase
• re.regex($e.target.hostname, `client-[0-9]+`) nocase

Ini tidak dapat digunakan jika jenis kolom adalah nilai yang dihitung. Contoh berikut tidak valid dan akan menghasilkan error kompilasi:

• $e.metadata.event_type = "NETWORK_DNS" nocase
• $e.network.ip_protocol = "TCP" nocase

Kolom berulang

Dalam Unified Data Model (UDM), beberapa kolom diberi label sebagai berulang, yang menunjukkan bahwa kolom tersebut adalah daftar nilai atau jenis pesan lainnya.

Kolom berulang dan ekspresi boolean

Ada 2 jenis ekspresi boolean yang bertindak pada kolom berulang:

1. Diubah
2. Tidak diubah

Pertimbangkan peristiwa berikut:

event_original {
  principal {
    // ip is a repeated field
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "host"
  }
}

Ekspresi yang diubah

Bagian berikut menjelaskan tujuan dan cara menggunakan pengubah any dan all dalam ekspresi.

apa pun

Jika salah satu elemen kolom berulang memenuhi kondisi, peristiwa secara keseluruhan akan memenuhi kondisi tersebut.

• event_original memenuhi any $e.principal.ip = "192.0.2.1".
• event_original gagal any $e.repeated_field.field_a = "9.9.9.9.

semua

Jika semua elemen kolom berulang memenuhi kondisi, peristiwa secara keseluruhan akan memenuhi kondisi tersebut.

• event_original memenuhi net.ip_in_range_cidr(all $e.principal.ip, "192.0.2.0/8").
• event_original gagal all $e.principal.ip = "192.0.2.2".

Catatan: Untuk menggunakan any atau all dengan fungsi, pengubah harus mendahului kolom berulang, bukan fungsi. Misalnya, re.regex(any $e.about.hostname, `server-[0-9]+`) valid, sedangkan any re.regex($e.about.hostname, `server-[0-9]+`) tidak valid.

Saat menulis kondisi dengan any atau all, perhatikan bahwa menegasikan kondisi dengan not mungkin tidak memiliki arti yang sama dengan menggunakan operator yang dinegasikan.

Contoh:

• not all $e.principal.ip = "192.168.12.16" memeriksa apakah tidak semua alamat IP cocok dengan 192.168.12.16, yang berarti aturan tersebut memeriksa apakah setidaknya satu alamat IP tidak cocok dengan 192.168.12.16.
• all $e.principal.ip != "192.168.12.16" memeriksa apakah semua alamat IP tidak cocok dengan 192.168.12.16, yang berarti aturan tersebut memeriksa bahwa tidak ada alamat IP yang cocok dengan 192.168.12.16.

Batasan:

• Operator any dan all hanya kompatibel dengan kolom berulang (bukan kolom skalar).
• any dan all tidak dapat digunakan untuk menggabungkan dua kolom berulang. Misalnya, any $e1.principal.ip = $e2.principal.ip tidak valid.
• Operator any dan all tidak didukung dengan ekspresi daftar referensi.

Ekspresi yang tidak dimodifikasi

Dengan ekspresi yang tidak diubah, setiap elemen di kolom berulang akan diperlakukan satu per satu. Jika kolom berulang peristiwa berisi elemen n, aturan akan diterapkan pada n salinan peristiwa, dengan setiap salinan memiliki salah satu elemen kolom berulang. Salinan ini bersifat sementara dan tidak disimpan.

Aturan ini diterapkan pada salinan berikut:

salinan peristiwa	principal.ip	principal.hostname
event_copy_1	"192.0.2.1"	"host"
event_copy_2	"192.0.2.2"	"host"
event_copy_3	"192.0.2.3"	"host"

Jika salah satu salinan peristiwa memenuhi semua kondisi yang tidak diubah pada kolom berulang, peristiwa secara keseluruhan akan memenuhi semua kondisi. Artinya, jika Anda memiliki beberapa kondisi pada kolom berulang, salinan peristiwa harus memenuhi semua kondisi tersebut. Contoh aturan berikut menggunakan set data contoh sebelumnya untuk menunjukkan perilaku ini.

Aturan berikut menampilkan satu kecocokan saat dijalankan terhadap set data contoh event_original, karena event_copy_1 memenuhi semua predikat peristiwa:

rule repeated_field_1 {
  meta:
  events:
    net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/8") // Checks if IP address matches 192.x.x.x
    $e.principal.ip = "192.0.2.1"
  condition:
    $e
}

Aturan berikut tidak menampilkan kecocokan saat dijalankan terhadap set data contoh event_original, karena tidak ada salinan peristiwa di $e.principal.ip yang memuaskan semua predikat peristiwa.

rule repeated_field_2 {
  meta:
  events:
    $e.principal.ip = "192.0.2.1"
    $e.principal.ip = "192.0.2.2"
  condition:
    $e
}

Ekspresi yang diubah pada kolom berulang kompatibel dengan ekspresi yang tidak diubah pada kolom berulang karena daftar elemennya sama untuk setiap salinan peristiwa. Pertimbangkan aturan berikut:

rule repeated_field_3 {
  meta:
  events:
    any $e.principal.ip = "192.0.2.1" 
    $e.principal.ip = "192.0.2.3"
  condition:
    $e
}

Aturan ini diterapkan pada salinan berikut:

salinan peristiwa	principal.ip	$e.principal.ip apa pun
event_copy_1	"192.0.2.1"	["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_2	"192.0.2.2"	["192.0.2.1", "192.0.2.2", "192.0.2.3"]
event_copy_3	"192.0.2.3"	["192.0.2.1", "192.0.2.2", "192.0.2.3"]

Dalam hal ini, semua salinan memenuhi any $e.principal.ip = "192.0.2.1", tetapi hanya event_copy_3 yang memenuhi $e.principal.ip = "192.0.2.3". Akibatnya, peristiwa secara keseluruhan akan cocok.

Cara lain untuk memahami jenis ekspresi ini adalah:

• Ekspresi pada kolom berulang yang menggunakan any atau all beroperasi pada daftar di event_original.
• Ekspresi pada kolom berulang yang tidak menggunakan any atau all beroperasi pada setiap peristiwa event_copy_n.

Kolom berulang dan placeholder

Kolom berulang berfungsi dengan penetapan placeholder. Serupa dengan ekspresi yang tidak diubah pada kolom berulang, salinan peristiwa dibuat untuk setiap elemen. Dengan menggunakan contoh event_copy yang sama, placeholder mengambil nilai kolom berulang event_copy_n, untuk setiap salinan peristiwa dengan n adalah nomor salinan peristiwa. Jika placeholder digunakan di bagian kecocokan, hal ini dapat menghasilkan beberapa kecocokan.

Contoh berikut menghasilkan satu kecocokan. Placeholder $ip sama dengan 192.0.2.1 untuk event_copy_1, yang memenuhi predikat dalam aturan. Contoh peristiwa kecocokan berisi satu elemen, event_original.

// Generates 1 match.
rule repeated_field_placeholder1 {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1"
    $host = $e.principal.hostname

  match:
    $host over 5m

  condition:
    $e
}

Contoh berikut menghasilkan tiga kecocokan. Placeholder $ip sama dengan nilai yang berbeda, untuk setiap salinan event_copy_n yang berbeda. Pengelompokan dilakukan pada $ip karena berada di bagian pencocokan. Oleh karena itu, Anda mendapatkan tiga kecocokan dengan setiap kecocokan memiliki nilai yang berbeda untuk variabel kecocokan $ip. Setiap kecocokan memiliki contoh peristiwa yang sama: satu elemen, event_original.

// Generates 3 matches.
rule repeated_field_placeholder2 {
  meta:
  events:
    $ip = $e.principal.ip
    net.ip_in_range_cidr($ip, "192.0.2.0/8") // Checks if IP matches 192.x.x.x

  match:
    $ip over 5m

  condition:
    $e
}

Catatan: any dan all tidak dapat digunakan saat menetapkan kolom berulang ke variabel placeholder atau bergabung dengan kolom peristiwa lain. Misalnya, any $e.principal.ip = $ip tidak valid.

Hasil menggunakan placeholder yang ditetapkan ke kolom berulang

Placeholder ditetapkan ke setiap elemen dari setiap kolom berulang, bukan seluruh daftar. Jadi, saat digunakan di bagian hasil, hasil hanya dihitung menggunakan elemen yang memenuhi bagian sebelumnya.

Pertimbangkan aturan berikut:

rule outcome_repeated_field_placeholder {
  meta:
  events:
    $ip = $e.principal.ip
    $ip = "192.0.2.1" or $ip = "192.0.2.2"
    $host = $e.principal.hostname

  match:
    $host over 5m

  outcome:
    $o = array_distinct($ip)

  condition:
    $e
}

Ada 4 tahap eksekusi untuk aturan ini. Tahap pertama adalah penyalinan peristiwa:

salinan peristiwa	$ip	$host	$e
event_copy_1	"192.0.2.1"	"host"	event_id
event_copy_2	"192.0.2.2"	"host"	event_id
event_copy_3	"192.0.2.3"	"host"	event_id

Bagian peristiwa kemudian akan memfilter baris yang tidak cocok dengan filter:

salinan peristiwa	$ip	$host	$e
event_copy_1	"192.0.2.1"	"host"	event_id
event_copy_2	"192.0.2.2"	"host"	event_id

event_copy_3 difilter karena "192.0.2.3" tidak memenuhi $ip = "192.0.2.1" or $ip = "192.0.2.2".

Bagian pencocokan kemudian akan mengelompokkan berdasarkan variabel pencocokan dan bagian hasil akan melakukan agregasi pada setiap grup:

$host	$o	$e
"host"	["192.0.2.1", "192.0.2.2"]	event_id

$o = array_distinct($ip) dihitung menggunakan $ip dari tahap sebelumnya, bukan tahap penyalinan peristiwa.

Terakhir, bagian kondisi akan memfilter setiap grup. Karena aturan ini hanya memeriksa keberadaan $e, baris dari sebelumnya akan menghasilkan satu deteksi.

$o tidak berisi semua elemen dari $e.principal.ip karena tidak semua elemen memenuhi semua kondisi di bagian peristiwa. Namun, semua elemen e.principal.ip akan muncul dalam sampel peristiwa karena sampel peristiwa menggunakan event_original.

Pengindeksan array

Anda dapat melakukan pengindeksan array pada kolom berulang. Untuk mengakses elemen kolom berulang ke-n, gunakan sintaksis daftar standar (elemen diberi indeks 0). Elemen di luar batas akan menampilkan nilai default.

• $e.principal.ip[0] = "192.168.12.16"
• $e.principal.ip[999] = "" Jika ada kurang dari 1.000 elemen, nilainya akan dievaluasi menjadi true.

Batasan:

• Indeks harus berupa literal bilangan bulat non-negatif. Misalnya, $e.principal.ip[-1] tidak valid.
• Nilai yang memiliki jenis int (misalnya, placeholder yang ditetapkan ke int) tidak dihitung.
• Pengindeksan array tidak dapat digabungkan dengan any atau all. Misalnya, any $e.intermediary.ip[0] tidak valid.
• Pengindeksan array tidak dapat digabungkan dengan sintaksis peta. Misalnya, $e.additional.fields[0]["key"] tidak valid.
• Jika jalur kolom berisi beberapa kolom berulang, semua kolom berulang harus menggunakan pengindeksan array. Misalnya, $e.intermediary.ip[0] tidak valid karena intermediary dan ip adalah kolom berulang, tetapi hanya ada indeks untuk ip.

Pesan berulang

Jika kolom message diulang, efek yang tidak diinginkan adalah mengurangi kemungkinan kecocokan. Hal ini diilustrasikan dalam contoh berikut.

Pertimbangkan peristiwa berikut:

event_repeated_message {
  // about is a repeated message field.
  about {
    // ip is a repeated string field.
    ip: [ "192.0.2.1", "192.0.2.2", "192.0.2.3" ]

    hostname: "alice"
  }
  about {
    hostname: "bob"
  }
}

Seperti yang dinyatakan untuk ekspresi yang tidak diubah pada kolom berulang, salinan sementara peristiwa dibuat untuk setiap elemen kolom berulang. Pertimbangkan aturan berikut:

rule repeated_message_1 {
  meta:
  events:
    $e.about.ip = "192.0.2.1" 
    $e.about.hostname = "bob"
  condition:
    $e
}

Aturan ini diterapkan pada salinan berikut:

salinan peristiwa	about.ip	about.hostname
event_copy_1	"192.0.2.1"	"alice"
event_copy_2	"192.0.2.2"	"alice"
event_copy_3	"192.0.2.3"	"alice"
event_copy_4	""	"bob"

Peristiwa tidak cocok dengan aturan karena tidak ada salinan peristiwa yang memenuhi semua ekspresi.

Pesan berulang dan pengindeksan array

Perilaku tidak terduga lainnya dapat terjadi saat menggunakan pengindeksan array dengan ekspresi yang tidak diubah pada kolom pesan berulang. Perhatikan contoh aturan berikut yang menggunakan pengindeksan array:

rule repeated_message_2 {
  meta:
  events:
    $e.about.ip = "192.0.2.1" 
    $e.about[1].hostname = "bob"
  condition:
    $e
}

Aturan ini diterapkan ke salinan berikut:

salinan peristiwa	about.ip	about[1].hostname
event_copy_1	"192.0.2.1"	"bob"
event_copy_2	"192.0.2.2"	"bob"
event_copy_3	"192.0.2.3"	"bob"
event_copy_4	""	"bob"

Karena event_copy_1 memenuhi semua ekspresi dalam repeated_message_2, peristiwa cocok dengan aturan.

Hal ini dapat menyebabkan perilaku yang tidak terduga karena aturan repeated_message_1 tidak memiliki pengindeksan array dan tidak menghasilkan kecocokan, sedangkan aturan repeated_message_2 menggunakan pengindeksan array dan menghasilkan kecocokan.

Komentar

Tetapkan komentar dengan dua karakter garis miring (// comment) atau komentar multibaris yang dimulai menggunakan karakter garis miring tanda bintang (/* comment */), seperti yang Anda lakukan di C.

Literal

Bilangan bulat dan bilangan pecahan non-negatif, string, boolean, dan literal ekspresi reguler didukung.

Literal string dan ekspresi reguler

Anda dapat menggunakan salah satu karakter tanda kutip berikut untuk mengapit string di YARA-L 2.0. Namun, teks yang dikutip ditafsirkan secara berbeda, bergantung pada teks yang Anda gunakan.

1. Tanda kutip ganda (") — Gunakan untuk string normal. Harus menyertakan karakter escape.
   Misalnya: "hello\tworld" —\t ditafsirkan sebagai tab

2. Tanda kutip belakang (`) — Gunakan untuk menafsirkan semua karakter secara harfiah.
   Misalnya: `hello\tworld` —\t tidak ditafsirkan sebagai tab

Untuk ekspresi reguler, Anda memiliki dua opsi.

Jika Anda ingin menggunakan ekspresi reguler secara langsung tanpa fungsi re.regex(), gunakan /regex/ untuk literal ekspresi reguler.

Anda juga dapat menggunakan literal string sebagai literal ekspresi reguler saat menggunakan fungsi re.regex(). Perhatikan bahwa untuk literal string tanda kutip ganda, Anda harus meng-escape karakter garis miring terbalik dengan karakter garis miring terbalik, yang dapat terlihat canggung.

Misalnya, ekspresi reguler berikut setara:

• re.regex($e.network.email.from, `.*altostrat\.com`)
• re.regex($e.network.email.from, ".*altostrat\\.com")
• $e.network.email.from = /.*altostrat\.com/

Google merekomendasikan penggunaan karakter kutipan balik untuk string dalam ekspresi reguler agar lebih mudah dibaca.

Operator

Anda dapat menggunakan operator berikut di YARA-L:

Operator	Deskripsi
=	equal/declaration
!=	tidak sama dengan
<	kurang dari
<=	kurang dari atau sama dengan
>	lebih besar dari
>=	lebih besar dari atau sama dengan

Variabel

Di YARA-L 2.0, semua variabel direpresentasikan sebagai $<variable name>.

Anda dapat menentukan jenis variabel berikut:

• Variabel peristiwa — Merepresentasikan grup peristiwa dalam bentuk normalisasi (UDM) atau peristiwa entity. Tentukan kondisi untuk variabel peristiwa di bagian events. Anda mengidentifikasi variabel peristiwa menggunakan nama, sumber peristiwa, dan kolom peristiwa. Sumber yang diizinkan adalah udm (untuk peristiwa yang dinormalisasi) dan graph (untuk peristiwa entity). Jika sumber dihilangkan, udm akan ditetapkan sebagai sumber default. Kolom peristiwa direpresentasikan sebagai rantai .<nama kolom> (misalnya, $e.field1.field2). Rantai kolom peristiwa selalu dimulai dari sumber tingkat atas (UDM atau Entitas).

• Variabel pencocokan — Deklarasikan di bagian match. Variabel pencocokan menjadi kolom pengelompokan untuk kueri, karena satu baris ditampilkan untuk setiap kumpulan variabel pencocokan yang unik (dan untuk setiap periode waktu). Saat aturan menemukan kecocokan, nilai variabel kecocokan akan ditampilkan. Tentukan apa yang diwakili oleh setiap variabel pencocokan di bagian events.

• Variabel placeholder — Deklarasikan dan tentukan di bagian events. Variabel placeholder mirip dengan variabel pencocokan. Namun, Anda dapat menggunakan variabel placeholder di bagian condition untuk menentukan kondisi kecocokan.

Catatan: Setiap variabel placeholder harus dipetakan ke kolom peristiwa. Misalnya, jika Anda hanya mereferensikan placeholder berikut dalam satu baris ini dalam aturan, aturan tersebut akan gagal dikompilasi karena $var tidak terikat dengan variabel peristiwa: $e.field != $var

Gunakan variabel pencocokan dan variabel placeholder untuk mendeklarasikan hubungan antara kolom peristiwa melalui kondisi join transitif (lihat Sintaksis Bagian Peristiwa untuk mengetahui detail selengkapnya).

Kata kunci

Kata kunci dalam YARA-L 2.0 tidak peka huruf besar/kecil. Misalnya, and atau AND setara. Nama variabel tidak boleh bertentangan dengan kata kunci. Misalnya, $AND atau $outcome tidak valid.

Berikut adalah kata kunci untuk aturan mesin deteksi: rule, meta, match, over, events, condition, outcome, options, and, or, not, nocase, in, regex, cidr, before, after, all, any, if, max, min, sum, array, array_distinct, count, count_distinct, is, dan null.

Maps

YARA-L mendukung akses peta untuk Structs dan Label.

Struct dan Label

Beberapa kolom UDM menggunakan jenis data Struct atau Label.

Untuk menelusuri pasangan nilai kunci tertentu di Struct dan Label, gunakan sintaksis peta standar:

// A Struct field.
$e.udm.additional.fields["pod_name"] = "kube-scheduler"
// A Label field.
$e.metadata.ingestion_labels["MetadataKeyDeletion"] = "startup-script"

Akses peta selalu menampilkan string.

Kasus yang didukung

Bagian Peristiwa dan Hasil

// Using a Struct field in the events section
events:
  $e.udm.additional.fields["pod_name"] = "kube-scheduler"

// Using a Label field in the outcome section
outcome:
  $value = array_distinct($e.metadata.ingestion_labels["MetadataKeyDeletion"])

Menetapkan nilai peta ke Placeholder

$placeholder = $u1.metadata.ingestion_labels["MetadataKeyDeletion"]

Menggunakan kolom peta dalam kondisi join

// using a Struct field in a join condition between two udm events $u1 and $u2
$u1.metadata.event_type = $u2.udm.additional.fields["pod_name"]

Kasus yang tidak didukung

Peta tidak didukung dalam kasus berikut.

Menggabungkan kata kunci any atau all dengan peta

Misalnya, hal berikut tidak didukung:

all $e.udm.additional.fields["pod_name"] = "kube-scheduler"

Jenis nilai lainnya

Sintaksis peta hanya dapat menampilkan nilai string. Dalam kasus jenis data Struct, sintaksis peta hanya dapat mengakses kunci yang nilainya berupa string. Anda tidak dapat mengakses kunci yang nilainya berupa jenis primitif lain seperti bilangan bulat.

Penanganan nilai duplikat

Akses peta selalu menampilkan satu nilai. Dalam kasus ekstrem yang tidak umum jika akses peta dapat merujuk ke beberapa nilai, akses peta akan secara deterministik menampilkan nilai pertama.

Hal ini dapat terjadi dalam salah satu kasus berikut:

• Label memiliki kunci duplikat.

  Struktur label merepresentasikan peta, tetapi tidak menerapkan keunikan kunci. Secara umum, peta harus memiliki kunci unik, sehingga Google Security Operations tidak menyarankan untuk mengisi label dengan kunci duplikat.

  Teks aturan $e.metadata.ingestion_labels["dupe-key"] akan menampilkan nilai pertama yang mungkin, val1, jika dijalankan pada contoh data berikut:

  // Disrecommended usage of label with a duplicate key:
  event {
    metadata{
      ingestion_labels{
        key: "dupe-key"
        value: "val1" // This is the first possible value for "dupe-key"
      }
      ingestion_labels{
        key: "dupe-key"
        value: "val2"
      }
    }
  }
  

• Label memiliki kolom berulang ancestor.

  Kolom berulang mungkin berisi label sebagai kolom turunan. Dua entri yang berbeda di kolom berulang tingkat atas mungkin berisi label yang memiliki kunci yang sama. Teks aturan $e.security_result.rule_labels["key"] akan menampilkan nilai pertama yang mungkin, val3, jika dijalankan pada contoh data berikut:

  event {
    // security_result is a repeated field.
    security_result {
      threat_name: "threat1"
      rule_labels {
        key: "key"
        value: "val3" // This is the first possible value for "key"
      }
    }
    security_result {
      threat_name: "threat2"
      rule_labels {
        key: "key"
        value: "val4"
      }
    }
  }
  

Functions

Bagian ini menjelaskan fungsi YARA-L 2.0 yang dapat Anda gunakan dalam aturan dan penelusuran mesin deteksi.

Catatan: Penggunaan variabel peristiwa $e bersifat opsional saat YARA-L digunakan dalam penelusuran. principal.hostname dan $e.principal.hostname didukung dalam penelusuran.

Fungsi ini dapat digunakan di bagian berikut dari aturan YARA-L:

• Bagian events.
• BOOL_CLAUSE kondisional di bagian hasil.

arrays.concat

Didukung di:

Aturan Penelusuran

arrays.concat(string_array, string_array)

Deskripsi

Menampilkan array string baru dengan menyalin elemen dari array string asli.

Jenis data parameter

ARRAY_STRINGS, ARRAY_STRINGS

Jenis hasil yang ditampilkan

ARRAY_STRINGS

Contoh kode

Contoh 1

Contoh berikut menyambungkan dua array string yang berbeda.

arrays.concat(["test1", "test2"], ["test3"]) = ["test1", "test2", "test3"]

Contoh 2

Contoh berikut menyambungkan array dengan string kosong.

arrays.concat([""], [""]) = ["", ""]

Contoh 3

Contoh berikut menyambungkan array kosong.

arrays.concat([], []) = []

arrays.join_string

Didukung di:

Aturan Penelusuran

arrays.join_string(array_of_strings, optional_delimiter)

Deskripsi

Mengonversi array string menjadi satu string yang dipisahkan oleh parameter opsional. Jika tidak ada pemisah yang diberikan, string kosong akan digunakan.

Jenis data parameter

ARRAY_STRINGS, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Berikut beberapa contoh cara menggunakan fungsi ini:

Contoh 1

Contoh ini menggabungkan array dengan elemen non-null dan pemisah.

arrays.join_string(["foo", "bar"], ",") = "foo,bar"

Contoh 2

Contoh ini menggabungkan array dengan elemen null dan pemisah.

arrays.join_string(["foo", NULL, "bar"], ",") = "foo,bar"

Contoh 3

Contoh ini menggabungkan array dengan elemen non-null dan tanpa pemisah.

arrays.join_string(["foo", "bar"]) = "foobar"

arrays.length

Didukung di:

Aturan Penelusuran

arrays.length(repeatedField)

Deskripsi

Menampilkan jumlah elemen kolom yang berulang.

Jenis data parameter

LIST

Jenis hasil yang ditampilkan

NUMBER

Contoh kode

Contoh 1

Menampilkan jumlah elemen kolom yang diulang.

arrays.length($e.principal.ip) = 2

Contoh 2

Jika ada beberapa kolom berulang di sepanjang jalur, menampilkan total jumlah elemen kolom berulang.

arrays.length($e.intermediary.ip) = 3

arrays.max

Didukung di:

Aturan Penelusuran

arrays.max(array_of_ints_or_floats)

Deskripsi

Menampilkan elemen terbesar dalam array atau nol jika array kosong.

Jenis data parameter

ARRAY_INTS|ARRAY_FLOATS

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Berikut beberapa contoh cara menggunakan fungsi ini:

Contoh 1

Contoh ini menampilkan elemen yang lebih besar dalam array bilangan bulat.

arrays.max([10, 20]) = 20.000000

Contoh 2

Contoh ini menampilkan elemen yang lebih besar dalam array float.

arrays.max([10.000000, 20.000000]) = 20.000000

arrays.min

Didukung di:

Aturan Penelusuran

arrays.min(array_of_ints_or_floats[, ignore_zeros=false])

Deskripsi

Menampilkan elemen terkecil dalam array atau nol jika array kosong. Jika argumen opsional kedua ditetapkan ke benar, elemen yang sama dengan nol akan diabaikan.

Jenis data parameter

ARRAY_INTS|ARRAY_FLOATS, BOOL

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Berikut beberapa contoh cara menggunakan fungsi ini:

Contoh 1

Contoh ini menampilkan elemen terkecil dalam array bilangan bulat.

arrays.min([10, 20]) = 10.000000

Contoh 2

Contoh ini menampilkan elemen terkecil dalam array float.

arrays.min([10.000000, 20.000000]) = 10.000000

Contoh 3

Contoh ini menampilkan elemen terkecil dalam array float, sekaligus mengabaikan nol.

arrays.min([10.000000, 20.000000, 0.0], true) = 10.000000

arrays.size

Didukung di:

Aturan Penelusuran

arrays.size( array )

Deskripsi

Menampilkan ukuran array. Menampilkan 0 untuk array kosong.

Jenis data parameter

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Contoh ini menggunakan array string yang berisi dua elemen.

arrays.size(["test1", "test2"]) = 2

Contoh 2

Contoh ini menggunakan array int yang berisi 3 elemen.

arrays.size([1, 2, 3]) = 3

Contoh 3

Contoh ini menggunakan array float yang berisi 1 elemen

arrays.size([1.200000]) = 1

Contoh 4

Contoh ini menggunakan array kosong.

arrays.size([]) = 0

arrays.index_to_float

Didukung di:

Aturan Penelusuran

arrays.index_to_float(array, index)

Deskripsi

Menampilkan elemen pada indeks array yang ditentukan. Elemen pada indeks tersebut ditampilkan sebagai float.

Indeks adalah nilai bilangan bulat yang mewakili posisi elemen dalam array. Secara default, elemen pertama array memiliki indeks 0, dan elemen terakhir memiliki indeks n-1, dengan n adalah ukuran array. Pengindeksan negatif memungkinkan akses ke elemen array yang relatif terhadap akhir array. Misalnya, indeks -1 mengacu pada elemen terakhir dalam array dan indeks -2 mengacu pada elemen kedua dari terakhir dalam array.

Jenis data parameter

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh berikut mengambil elemen pada indeks 1 dari array float.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 1) // 2.1

Contoh 2

Contoh berikut mengambil elemen pada indeks -1 dari array float.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], -1) // 4.6

Contoh 3

Contoh berikut mengambil elemen untuk indeks yang lebih besar dari ukuran array.

arrays.index_to_float([1.2, 2.1, 3.5, 4.6], 6) // 0.0

Contoh 4

Contoh berikut mengambil elemen dari array kosong.

arrays.index_to_float([], 0) // 0.0

Contoh 5

Contoh berikut mengambil elemen pada indeks 1 dari array string.

arrays.index_to_float(["1.2", "3.3", "2.4"], 1) // 3.3

Contoh 6

Contoh berikut mengambil elemen pada indeks 2 dari array bilangan bulat.

arrays.index_to_float([1, 3, 2], 2) // 2.0

arrays.index_to_int

Didukung di:

Aturan Penelusuran

arrays.index_to_int(array_of_inputs, index)

Deskripsi

Menampilkan nilai pada indeks tertentu dalam array sebagai bilangan bulat.

Indeks adalah nilai bilangan bulat yang mewakili posisi elemen dalam array. Secara default, elemen pertama array memiliki indeks 0, dan elemen terakhir memiliki indeks n-1, dengan n adalah ukuran array. Pengindeksan negatif memungkinkan akses ke elemen array yang relatif terhadap akhir array. Misalnya, indeks -1 mengacu pada elemen terakhir dalam array dan indeks -2 mengacu pada elemen kedua dari terakhir dalam array.

Jenis data parameter

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Panggilan fungsi ini menampilkan 0 jika nilai pada indeks adalah string non-numerik.

arrays.index_to_int(["str0", "str1", "str2"], 1) = 0

Contoh 2

Fungsi ini menampilkan elemen pada indeks -1.

arrays.index_to_int(["44", "11", "22", "33"], -1) = 33

Contoh 3

Menampilkan 0 untuk elemen di luar batas.

arrays.index_to_int(["44", "11", "22", "33"], 5) = 0

Contoh 4

Fungsi ini mengambil elemen dari array float pada indeks 1.

arrays.index_to_int([1.100000, 1.200000, 1.300000], 1) = 1

Contoh 5

Fungsi ini mengambil elemen dari array int pada indeks 0.

arrays.index_to_int([1, 2, 3], 0) = 1

arrays.index_to_str

Didukung di:

Aturan Penelusuran

arrays.index_to_str(array, index)

Deskripsi

Menampilkan elemen pada indeks tertentu dari array sebagai string. Indeks adalah nilai bilangan bulat yang mewakili posisi elemen dalam array. Secara default, elemen pertama array memiliki indeks 0, dan elemen terakhir memiliki indeks n-1, dengan n adalah ukuran array. Pengindeksan negatif memungkinkan akses ke elemen array dari akhir array. Misalnya, indeks -1 mengacu pada elemen terakhir dalam array dan indeks -2 mengacu pada elemen kedua dari terakhir dalam array.

Jenis data parameter

ARRAY_STRINGS|ARRAY_INTS|ARRAY_FLOATS, INT

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut mengambil elemen pada indeks 1 dari array string.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 1) // "test2"

Contoh 2

Contoh berikut mengambil elemen pada indeks -1 (elemen terakhir array) dari array string.

arrays.index_to_str(["test1", "test2", "test3", "test4"], -1) // "test4"

Contoh 3

Contoh berikut mengambil elemen untuk indeks yang lebih besar dari ukuran array, yang menampilkan string kosong.

arrays.index_to_str(["test1", "test2", "test3", "test4"], 6) // ""

Contoh 4

Contoh berikut mengambil elemen dari array kosong.

arrays.index_to_str([], 0) // ""

Contoh 5

Contoh berikut mengambil elemen pada indeks 0 dari array float. Output ditampilkan sebagai string.

arrays.index_to_str([1.200000, 3.300000, 2.400000], 0) // "1.2"

Contoh 6

Contoh berikut mengambil elemen pada indeks 2 dari array bilangan bulat. Output-nya berupa string.

arrays.index_to_str([1, 3, 2], 2) // "2"

cast.as_bool

Didukung di:

Aturan Penelusuran

cast.as_bool(string_or_int)

Deskripsi

Fungsi mengonversi nilai int atau string menjadi nilai bool. Panggilan fungsi dengan nilai yang tidak dapat ditransmisikan akan menampilkan SALAH. Menampilkan TRUE hanya untuk bilangan bulat 1 dan string 'true' yang tidak peka huruf besar/kecil.

Jenis data parameter

INT|STRING

Jenis hasil yang ditampilkan

BOOL

Contoh kode

Contoh 1

Contoh ini menunjukkan cara mentransmisikan string non-boolean

cast.as_bool("123") = false

Contoh 2

Bilangan bulat yang benar (1)

cast.as_bool(1) = true

Contoh 3

String yang benar

cast.as_bool("true") = true

Contoh 4

String truthy kapital

cast.as_bool("TRUE") = true

Contoh 5

Bilangan bulat negatif

cast.as_bool(-1) = false

Contoh 6

Bilangan bulat salah (0)

cast.as_bool(0) = false

Contoh 7

string kosong

cast.as_bool("") = false

cast.as_float

Didukung di:

Aturan Penelusuran

cast.as_float(string_to_cast)

Deskripsi

Mengonversi string numerik menjadi float. Setiap panggilan fungsi dengan nilai yang tidak dapat ditransmisikan akan menampilkan 0. Float mempertahankan presisi hingga 7 digit desimal.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Mentransmisikan string non-numerik akan menampilkan 0.

cast.as_float("str") = 0.0000000

Contoh 2

Mentransmisikan string kosong akan menampilkan 0.

cast.as_float("") = 0.0000000

Contoh 3

Mentransmisikan string numerik yang valid akan menampilkan nilai float.

cast.as_float("1.012345678") = 1.0123456

sidik jari

Didukung di:

Aturan

hash.fingerprint2011(byteOrString)

Deskripsi

Fungsi ini menghitung hash fingerprint2011 dari urutan atau string byte input. Fungsi ini menampilkan nilai INT tanpa tanda tangan dalam rentang [2, 0xFFFFFFFFFFFFFFFF].

Catatan: Fungsi ini tidak boleh digunakan sebagai hash aman kriptografis.

Jenis data parameter

BTYE, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

id_fingerprint = hash.fingerprint2011("user123")

grup

Didukung di:

Penelusuran

group(field1, field2, field3, ...)

Deskripsi

Mengelompokkan kolom dari jenis yang serupa ke dalam variabel placeholder.

Dalam penelusuran UDM, kolom gabungan digunakan untuk menelusuri beberapa kolom dengan jenis yang serupa. Fungsi grup mirip dengan kolom yang dikelompokkan, kecuali bahwa fungsi ini memungkinkan Anda memilih kolom yang ingin dikelompokkan untuk memicu deteksi. Anda dapat menggunakan fungsi grup untuk mengumpulkan informasi tentang entitas tertentu (misalnya, nama host, alamat IP, atau userid) di berbagai Jenis kata benda.

Catatan: Untuk penelusuran, Anda dapat menggunakan kolom yang dikelompokkan di bagian peristiwa, tetapi tidak di bagian kecocokan dan hasil.

Contoh kode

Contoh 1

Mengelompokkan semua alamat IP dan memberikan jumlah menurun dari alamat IP yang paling umum dalam rentang waktu yang dipindai.

$ip = group(principal.ip, about.ip, target.ip)
$ip != ""
match:
  $ip
outcome:
  $count = count_distinct(metadata.id)
order:
  $count desc

hash.sha256

Didukung di:

Aturan

hash.sha256(string)

Deskripsi

Menampilkan hash SHA-256 dari string input.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh ini menunjukkan hash SHA-256 saat input adalah string yang valid.

hash.sha256("str") = "8c25cb3686462e9a86d2883c5688a22fe738b0bbc85f458d2d2b5f3f667c6d5a"

Contoh 2

Contoh ini menunjukkan hash SHA-256 saat inputnya adalah string kosong.

hash.sha256("") = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

math.abs

Didukung di:

Aturan Penelusuran

math.abs(numericExpression)

Deskripsi

Menampilkan nilai absolut dari ekspresi bilangan bulat atau float.

Jenis data parameter

NUMBER

Jenis hasil yang ditampilkan

NUMBER

Contoh kode

Contoh 1

Contoh ini menampilkan True jika peristiwa terjadi lebih dari 5 menit dari waktu yang ditentukan (dalam detik dari epoch Unix), terlepas dari apakah peristiwa terjadi sebelum atau setelah waktu yang ditentukan. Panggilan ke math.abs tidak dapat bergantung pada beberapa variabel atau placeholder. Misalnya, Anda tidak dapat mengganti nilai waktu hardcoded 1643687343 dalam contoh berikut dengan $e2.metadata.event_timestamp.seconds.

300 < math.abs($e1.metadata.event_timestamp.seconds - 1643687343)

math.ceil

Didukung di:

Aturan Penelusuran

math.ceil(number)

Deskripsi

Menampilkan bilangan bulat terkecil yang tidak kurang dari bilangan yang diberikan (membulatkan ke atas). Akan menampilkan 0 jika input null atau terlalu besar untuk muat dalam int64.

Jenis data parameter

FLOAT

Jenis hasil yang ditampilkan

INT

Contoh kode

Bagian ini berisi contoh penggunaan math.ceil.

Contoh 1

Contoh ini menampilkan bilangan bulat.

math.ceil(2.000000) = 2

Contoh 2

Contoh ini menampilkan bilangan bulat atas dari angka negatif.

math.ceil(-1.200000) = -1

Contoh 3

Contoh ini menampilkan 0 sebagai bilangan bulat atas dari angka yang terlalu besar untuk bilangan bulat 64 bit.

math.ceil(184467440737095516160.0) = 0

math.floor

Didukung di:

Aturan Penelusuran

math.floor(float_val)

Deskripsi

Menampilkan nilai bilangan bulat terbesar yang tidak lebih besar dari nilai yang diberikan (membulatkan ke bawah). Menampilkan 0 jika input null atau terlalu besar untuk dimasukkan ke dalam int64.

Jenis data parameter

FLOAT

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Contoh ini menunjukkan kasus bilangan positif.

math.floor(1.234568) = 1

Contoh 2

Contoh ini menunjukkan kasus angka negatif.

math.floor(-1.234568) = -2

Contoh 3

Contoh ini menunjukkan kasus nol.

math.floor(0.000000) = 0

math.geo_distance

Didukung di:

Aturan

math.geo_distance(longitude1, latitude1, longitude2, latitude2))

Deskripsi

Menampilkan jarak antara dua geolokasi (koordinat). Akan menampilkan -1 jika koordinat geografis tidak valid.

Jenis data parameter

FLOAT, FLOAT, FLOAT, FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menampilkan jarak jika semua parameter adalah koordinat yang valid.

math.geo_distance(-122.020287, 37.407574, -122.021810, 37.407574) = 134.564318

Contoh 2

Contoh ini menampilkan jarak saat salah satu parameternya adalah koordinat yang terpotong.

math.geo_distance(-122.000000, 37.407574, -122.021810, 37.407574) = 1926.421905

Contoh 3

Contoh ini menampilkan -1 jika salah satu parameter adalah koordinat yang tidak valid.

math.geo_distance(-122.897680, 37.407574, -122.021810, 97.407574) = -1.000000

Contoh 4

Contoh ini menampilkan 0 jika koordinat sama.

math.geo_distance(-122.897680, 37.407574, -122.897680, 37.407574) = 0.000000

math.is_increasing

Didukung di:

Aturan Penelusuran

math.is_increasing(num1, num2, num3)

Deskripsi

Mengambil daftar nilai numerik (bilangan bulat atau ganda) dan menampilkan True jika nilainya dalam urutan menaik, dan False jika sebaliknya.

Jenis data parameter

INT|FLOAT, INT|FLOAT, INT|FLOAT

Jenis hasil yang ditampilkan

BOOL

Contoh kode

Contoh 1

Contoh ini menyertakan nilai seperti stempel waktu dalam detik.

math.is_increasing(1716769112, 1716769113, 1716769114) = true

Contoh 2

Contoh ini mencakup satu nilai ganda negatif, satu nilai INT64 nol, dan satu nilai INT64 positif.

math.is_increasing(-1.200000, 0, 3) = true

Contoh 3

Contoh ini mencakup satu nilai ganda negatif, satu INT64 nol, dan satu nilai INT64 negatif.

math.is_increasing(-1.200000, 0, -3) = false

Contoh 4

Contoh ini mencakup dua nilai ganda negatif dan satu nilai INT64 nol.

math.is_increasing(-1.200000, -1.50000, 0) = false

Contoh 5

Contoh ini menyertakan satu nilai ganda negatif dan dua nilai yang sama.

math.is_increasing(-1.200000, 0, 0) = false

math.log

Didukung di:

Aturan Penelusuran

math.log(numericExpression)

Deskripsi

Menampilkan nilai log natural dari ekspresi bilangan bulat atau float.

Jenis data parameter

NUMBER

Jenis hasil yang ditampilkan

NUMBER

Contoh kode

Contoh 1

math.log($e1.network.sent_bytes) > 20

math.pow

Didukung di:

Aturan Penelusuran

math.pow(base, exponent)

Deskripsi

Menampilkan nilai arg pertama yang dihitung pangkatnya dengan arg kedua. Menampilkan 0 jika terjadi overflow.

Jenis data parameter

basis: INT|FLOAT eksponen: INT|FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menunjukkan kasus bilangan bulat.

math.pow(2, 2) // 4.00

Contoh 2

Contoh ini menunjukkan kasus dasar pecahan.

math.pow(2.200000, 3) // 10.648

Contoh 3

Contoh ini menunjukkan kasus dasar pecahan dan daya.

math.pow(2.200000, 1.200000) // 2.575771

Contoh 4

Contoh ini menunjukkan kasus daya negatif.

math.pow(3, -3) // 0.037037

Contoh 5

Contoh ini menunjukkan kasus pangkat pecahan.

math.pow(3, -1.200000) // 0.267581

Contoh 6

Contoh ini menunjukkan kasus dasar negatif.

math.pow(-3, -3) // -0.037037

Contoh 7

Contoh ini menunjukkan kasus dasar nol.

math.pow(0, 3) // 0

Contoh 8

Contoh ini menunjukkan kasus daya nol.

math.pow(9223372036854775807, 0) // 1

Contoh 9

Contoh ini menunjukkan kasus dasar yang besar.

math.pow(9223372036854775807, 1.200000) // 57262152889751593549824

math.random

Didukung di:

Aturan Penelusuran

math.random()

Deskripsi

Menghasilkan nilai pseudo-acak jenis DOUBLE dalam rentang [0, 1), termasuk 0 dan tidak termasuk 1.

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh berikut memeriksa apakah nilai acak berada dalam rentang [0, 1). none if(math.random() >= 0 and math.random() < 1) = true

math.round

Didukung di:

Penelusuran

math.round(numericExpression, decimalPlaces)

Deskripsi

Menampilkan nilai yang dibulatkan ke bilangan bulat terdekat atau ke jumlah tempat desimal yang ditentukan.

Jenis data parameter

NUMBER

Jenis hasil yang ditampilkan

NUMBER

Contoh kode

math.round(10.7) // returns 11
math.round(1.2567, 2) // returns 1.25
math.round(-10.7) // returns -11
math.round(-1.2) // returns -1
math.round(4) // returns 4, math.round(integer) returns the integer

math.sqrt

Didukung di:

Aturan Penelusuran

math.sqrt(number)

Deskripsi

Menampilkan akar kuadrat dari angka yang diberikan. Menampilkan 0 jika angka negatif.

Jenis data parameter

INT|FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menampilkan akar kuadrat dari argumen int.

math.sqrt(3) = 1.732051

Contoh 2

Contoh ini menampilkan akar kuadrat dari argumen int negatif.

math.sqrt(-3) = 0.000000

Contoh 3

Contoh ini menampilkan akar kuadrat dari argumen nol.

math.sqrt(0) = 0.000000

Contoh 4

Contoh ini menampilkan akar kuadrat dari argumen float.

math.sqrt(9.223372) = 3.037000

Contoh 5

Contoh ini menampilkan akar kuadrat dari argumen float negatif.

math.sqrt(-1.200000) = 0.000000

metrik

Didukung di:

Aturan

Fungsi metrik dapat menggabungkan data historis dalam jumlah besar. Anda dapat menggunakannya dalam aturan menggunakan metrics.functionName() di bagian hasil.

Untuk informasi selengkapnya, lihat Metrik YARA-L.

net.ip_in_range_cidr

Didukung di:

Aturan Penelusuran

net.ip_in_range_cidr(ipAddress, subnetworkRange)

Deskripsi

Menampilkan true jika alamat IP yang diberikan berada dalam subnetwork yang ditentukan.

Anda dapat menggunakan YARA-L untuk menelusuri peristiwa UDM di semua alamat IP dalam subjaringan menggunakan pernyataan net.ip_in_range_cidr(). IPv4 dan IPv6 didukung.

Untuk menelusuri di seluruh rentang alamat IP, tentukan kolom UDM IP dan rentang CIDR. YARA-L dapat menangani kolom alamat IP tunggal dan berulang.

Untuk menelusuri di seluruh rentang alamat IP, tentukan kolom UDM ip dan rentang Classless Inter-Domain Routing (CIDR). YARA-L dapat menangani kolom alamat IP tunggal dan berulang.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

BOOL

Contoh kode

Contoh 1

Contoh IPv4:

net.ip_in_range_cidr($e.principal.ip, "192.0.2.0/24")

Contoh 2

Contoh IPv6:

net.ip_in_range_cidr($e.network.dhcp.yiaddr, "2001:db8::/32")

Untuk contoh aturan yang menggunakan pernyataan net.ip_in_range_cidr(), lihat contoh aturan di Satu Peristiwa dalam Rentang Alamat IP.)

re.regex

Didukung di:

Aturan Penelusuran

Anda dapat menentukan pencocokan ekspresi reguler di YARA-L 2.0 menggunakan salah satu sintaksis berikut:

• Menggunakan sintaksis YARA-L — Terkait dengan peristiwa. Berikut adalah representasi umum sintaksis ini:

  $e.field = /regex/
  

• Menggunakan sintaksis YARA-L — Sebagai fungsi yang menggunakan parameter berikut:

  • Kolom tempat ekspresi reguler diterapkan.
  • Ekspresi reguler yang ditentukan sebagai string.

  Berikut adalah representasi umum sintaksis ini:

  re.regex($e.field, `regex`)
  

Deskripsi

Fungsi ini menampilkan true jika string berisi substring yang cocok dengan ekspresi reguler yang diberikan. Anda tidak perlu menambahkan .* ke awal atau akhir ekspresi reguler.

Catatan

• Untuk mencocokkan string yang sama persis atau hanya awalan atau akhiran, sertakan karakter anchor ^ (awal) dan $ (akhir) dalam ekspresi reguler. Misalnya, /^full$/ cocok dengan "full" persis, sedangkan /full/ dapat cocok dengan "fullest", "lawfull", dan "joyfully".
• Jika kolom UDM menyertakan karakter baris baru, regexp hanya cocok dengan baris pertama kolom UDM. Untuk menerapkan pencocokan kolom UDM lengkap, tambahkan (?s) ke ekspresi reguler. Misalnya, ganti /.*allUDM.*/ dengan /(?s).*allUDM.*/.
• Anda dapat menggunakan pengubah nocase setelah string untuk menunjukkan bahwa penelusuran harus mengabaikan kapitalisasi.

Jenis data parameter

STRING, STRING

Jenis ekspresi parameter

ANY, ANY

Jenis hasil yang ditampilkan

BOOL

Contoh kode

Contoh 1

// Equivalent to $e.principal.hostname = /google/
re.regex($e.principal.hostname, "google")

re.capture

Didukung di:

Aturan Penelusuran

re.capture(stringText, regex)

Deskripsi

Merekam (mengekstrak) data dari string menggunakan pola ekspresi reguler yang disediakan dalam argumen.

Fungsi ini menggunakan dua argumen:

• stringText: string asli yang akan ditelusuri.
• regex: ekspresi reguler yang menunjukkan pola yang akan ditelusuri.

Ekspresi reguler dapat berisi 0 atau 1 grup tangkapan dalam tanda kurung. Jika ekspresi reguler berisi 0 grup tangkapan, fungsi akan menampilkan seluruh substring pertama yang cocok. Jika ekspresi reguler berisi 1 grup tangkapan, ekspresi tersebut akan menampilkan substring pertama yang cocok untuk grup tangkapan. Menentukan dua atau beberapa grup pengambilan akan menampilkan error compiler.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Dalam contoh ini, jika $e.principal.hostname berisi "aaa1bbaa2", hal berikut akan benar, karena fungsi tersebut menampilkan instance pertama. Contoh ini tidak memiliki grup tangkapan.

"aaa1" = re.capture($e.principal.hostname, "a+[1-9]")

Contoh 2

Contoh ini menangkap semua hal setelah simbol @ dalam email. Jika kolom $e.network.email.from adalah [e-mail], contoh akan menampilkan google.com. Contoh berikut berisi satu grup pengambilan.

"google.com" = re.capture($e.network.email.from , "@(.*)")

Contoh 3

Jika ekspresi reguler tidak cocok dengan substring apa pun dalam teks, fungsi ini akan menampilkan string kosong. Anda dapat menghilangkan peristiwa yang tidak cocok dengan mengecualikan string kosong, yang sangat penting saat Anda menggunakan re.capture() dengan ketidaksetaraan:

// Exclude the empty string to omit events where no match occurs.
"" != re.capture($e.network.email.from , "@(.*)")

// Exclude a specific string with an inequality.
"google.com" != re.capture($e.network.email.from , "@(.*)")

re.replace

Didukung di:

Aturan Penelusuran

re.replace(stringText, replaceRegex, replacementText)

Deskripsi

Melakukan penggantian ekspresi reguler.

Fungsi ini menggunakan tiga argumen:

• stringText: string asli.
• replaceRegex: ekspresi reguler yang menunjukkan pola yang akan ditelusuri.
• replacementText: Teks yang akan disisipkan ke setiap kecocokan.

Menampilkan string baru yang berasal dari stringText asli, dengan semua substring yang cocok dengan pola di replaceRegex diganti dengan nilai di replacementText. Anda dapat menggunakan angka yang di-escape dengan garis miring terbalik (\1 hingga \9) dalam replacementText untuk menyisipkan teks yang cocok dengan grup bertanda kurung yang sesuai dalam pola replaceRegex. Gunakan \0 untuk merujuk ke seluruh teks yang cocok.

Fungsi ini menggantikan kecocokan yang tidak tumpang-tindih dan akan memprioritaskan penggantian kejadian pertama yang ditemukan. Misalnya, re.replace("banana", "ana", "111") menampilkan string "b111na".

Jenis data parameter

STRING, STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh ini mengambil semua hal setelah simbol @ dalam email, mengganti com dengan org, lalu menampilkan hasilnya. Perhatikan penggunaan fungsi bertingkat.

"[e-mail]" = re.replace($e.network.email.from, "com", "org")

Contoh 2

Contoh ini menggunakan digit yang di-escape dengan garis miring terbalik dalam argumen replacementText untuk mereferensikan kecocokan dengan pola replaceRegex.

"test1.com.google" = re.replace(
                       $e.principal.hostname, // holds "test1.test2.google.com"
                       "test2\.([a-z]*)\.([a-z]*)",
                       "\\2.\\1"  // \\1 holds "google", \\2 holds "com"
                     )

Contoh 3

Perhatikan kasus berikut saat menangani string kosong dan re.replace():

Menggunakan string kosong sebagai replaceRegex:

// In the function call below, if $e.principal.hostname contains "name",
// the result is: 1n1a1m1e1, because an empty string is found next to
// every character in `stringText`.
re.replace($e.principal.hostname, "", "1")

Untuk mengganti string kosong, Anda dapat menggunakan "^$" sebagai replaceRegex:

// In the function call below, if $e.principal.hostname contains the empty
// string, "", the result is: "none".
re.replace($e.principal.hostname, "^$", "none")

sample_rate

Didukung di:

Aturan

optimization.sample_rate(byteOrString, rateNumerator, rateDenominator)

Deskripsi

Fungsi ini menentukan apakah akan menyertakan peristiwa berdasarkan strategi sampling deterministik. Fungsi ini menampilkan:

• true untuk sebagian nilai input, setara dengan (rateNumerator / rateDenominator), yang menunjukkan bahwa peristiwa harus disertakan dalam sampel.
• false yang menunjukkan bahwa peristiwa tidak boleh disertakan dalam sampel.

Fungsi ini berguna untuk skenario pengoptimalan saat Anda hanya ingin memproses sebagian peristiwa. Setara dengan:

hash.fingerprint2011(byteOrString) % rateDenominator < rateNumerator

Jenis data parameter

• byteOrString: Ekspresi yang dievaluasi menjadi BYTE atau STRING.
• rateNumerator: 'INT'
• rateDenominator: 'INT'

Jenis hasil yang ditampilkan

BOOL

Contoh kode

events:
    $e.metadata.event_type = "NETWORK_CONNECTION"
    $asset_id = $e.principal.asset.asset_id
    optimization.sample_rate($e.metadata.id, 1, 5) // Only 1 out of every 5 events

  match:
    $asset_id over 1h

  outcome:
    $event_count = count_distinct($e.metadata.id)
  // estimate the usage by multiplying by the inverse of the sample rate
    $usage_past_hour = sum(5.0 * $e.network.sent_bytes)

 condition:
  // Requiring a certain number of events after sampling avoids bias (e.g. a
  // device with just 1 connection will still show up 20% of the time and
  // if we multiply that traffic by 5, we'll get an incorrect estimate)
  $e and ($usage_past_hour > 1000000000) and $event_count >= 100

strings.base64_decode

Didukung di:

Aturan Penelusuran

strings.base64_decode(encodedString)

Deskripsi

Menampilkan string yang berisi versi string yang dienkode dan didekode base64.

Fungsi ini menggunakan satu string berenkode base64 sebagai argumen. Jika encodedString bukan string berenkode base64 yang valid, fungsi akan menampilkan encodedString tanpa perubahan.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

"test" = strings.base64_decode($e.principal.domain.name)

strings.coalesce

Didukung di:

Aturan Penelusuran

strings.coalesce(a, b, c, ...)

Deskripsi

Fungsi ini menggunakan argumen dalam jumlah tidak terbatas dan menampilkan nilai ekspresi pertama yang tidak dievaluasi menjadi string kosong (misalnya, "nilai non-nol"). Jika semua argumen bernilai string kosong, panggilan fungsi akan menampilkan string kosong.

Argumen dapat berupa literal, kolom peristiwa, atau panggilan fungsi. Semua argumen harus berjenis STRING. Jika argumen adalah kolom peristiwa, atribut harus berasal dari peristiwa yang sama.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut menyertakan variabel string sebagai argumen. Kondisi ini dievaluasi menjadi benar jika (1) $e.network.email.from adalah [e-mail] atau (2) $e.network.email.from kosong dan $e.network.email.to adalah [e-mail].

"[e-mail]" = strings.coalesce($e.network.email.from, $e.network.email.to)

Contoh 2

Contoh berikut memanggil fungsi coalesce dengan lebih dari dua argumen. Kondisi ini membandingkan alamat IP non-null pertama dari peristiwa $e dengan nilai dalam daftar referensi ip_watchlist. Urutan penggabungan argumen dalam panggilan ini sama dengan urutan pengurutannya dalam kondisi aturan:

1. $e.principal.ip dievaluasi terlebih dahulu.
2. $e.src.ip dievaluasi berikutnya.
3. $e.target.ip dievaluasi berikutnya.
4. Terakhir, string "No IP" ditampilkan sebagai nilai default jika kolom ip sebelumnya tidak ditetapkan.

strings.coalesce($e.principal.ip, $e.src.ip, $e.target.ip, "No IP") in %ip_watchlist

Contoh 3

Contoh berikut mencoba menggabungkan principal.hostname dari peristiwa $e1 dan peristiwa $e2. Tindakan ini akan menampilkan error compiler karena argumennya adalah variabel peristiwa yang berbeda.

// returns a compiler error
"test" = strings.coalesce($e1.principal.hostname, $e2.principal.hostname)

strings.concat

Didukung di:

Aturan Penelusuran

strings.concat(a, b, c, ...)

Deskripsi

Menampilkan penyambungan item dalam jumlah tidak terbatas, yang masing-masing dapat berupa string, bilangan bulat, atau float.

Jika argumen adalah kolom peristiwa, atribut harus berasal dari peristiwa yang sama.

Jenis data parameter

STRING, FLOAT, INT

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut menyertakan variabel string dan variabel bilangan bulat sebagai argumen. principal.hostname dan principal.port berasal dari peristiwa yang sama, $e, dan digabungkan untuk menampilkan string.

"google:80" = strings.concat($e.principal.hostname, ":", $e.principal.port)

Contoh 2

Contoh berikut menyertakan variabel string dan literal string sebagai argumen.

"google-test" = strings.concat($e.principal.hostname, "-test") // Matches the event when $e.principal.hostname = "google"

Contoh 3

Contoh berikut menyertakan variabel string dan literal float sebagai argumen. Jika direpresentasikan sebagai string, float yang merupakan bilangan bulat akan diformat tanpa titik desimal (misalnya, 1,0 direpresentasikan sebagai "1"). Selain itu, float yang melebihi enam belas digit desimal akan terpotong ke tempat desimal ke enam belas.

"google2.5" = strings.concat($e.principal.hostname, 2.5)

Contoh 4

Contoh berikut menyertakan variabel string, literal string, variabel bilangan bulat, dan literal float sebagai argumen. Semua variabel berasal dari peristiwa yang sama, $e, dan digabungkan dengan literal untuk menampilkan string.

"google-test802.5" = strings.concat($e.principal.hostname, "-test", $e.principal.port, 2.5)

Contoh 5

Contoh berikut mencoba menyambungkan principal.port dari peristiwa $e1, dengan principal.hostname dari peristiwa $e2. Tindakan ini akan menampilkan error compiler karena argumennya adalah variabel peristiwa yang berbeda.

// Will not compile
"test" = strings.concat($e1.principal.port, $e2.principal.hostname)

strings.contains

Didukung di:

Aturan Penelusuran

strings.contains( str, substr )

Deskripsi

Menampilkan true jika string tertentu berisi substring yang ditentukan. Jika tidak, nilai salah (false) akan ditampilkan.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

BOOL

Contoh kode

Contoh 1

Contoh ini menampilkan benar karena string memiliki substring "is".

strings.contains("thisisastring", "is") = true

Contoh 2

Contoh ini menampilkan nilai salah karena string tidak memiliki substring "that".

strings.contains("thisisastring", "that") = false

strings.count_substrings

Didukung di:

Aturan Penelusuran

strings.count_substrings(string_to_search_in, substring_to_count)

Deskripsi

Jika diberi string dan substring, akan menampilkan int64 dari jumlah kemunculan substring yang tidak tumpang-tindih dalam string.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Bagian ini berisi contoh yang menghitung frekuensi kemunculan substring dalam string tertentu.

Contoh 1

Contoh ini menggunakan string non-null dan karakter substring tunggal non-null.

strings.count_substrings("this`string`has`four`backticks", "`") = 4

Contoh 2

Contoh ini menggunakan string non-null dan substring non-null yang lebih besar dari satu karakter.

strings.count_substrings("str", "str") = 1

Contoh 3

Contoh ini menggunakan string non-null dan substring kosong.

strings.count_substrings("str", "") = 0

Contoh 4

Contoh ini menggunakan string kosong dan substring non-null yang lebih besar dari satu karakter.

strings.count_substrings("", "str") = 0

Contoh 5

Contoh ini menggunakan string kosong dan substring kosong.

strings.count_substrings("", "") = 0

Contoh 6

Contoh ini menggunakan string non-null dan substring non-null yang lebih besar dari satu karakter dan lebih besar dari satu kemunculan.

strings.count_substrings("fooABAbarABAbazABA", "AB") = 3

Contoh 7

Contoh ini menggunakan string non-null dan substring non-null yang lebih besar dari satu karakter dan lebih besar dari satu kemunculan. Ini menyoroti batasan dengan kemunculan substring yang tumpang-tindih

strings.count_substrings("ABABABA", "ABA") = 2

strings.extract_domain

Didukung di:

Aturan Penelusuran

strings.extract_domain(url_string)

Deskripsi

Mengekstrak domain dari string.

Catatan: Fungsi ini tidak melakukan normalisasi Unicode.

Catatan: Data akhiran publik di publicsuffix.org juga berisi domain pribadi. Fungsi ini tidak memperlakukan domain pribadi sebagai akhiran publik. Misalnya, jika us.com adalah domain pribadi dalam data akhiran publik, ("foo.us.com") akan menampilkan us.com (akhiran publik com ditambah label sebelumnya us) dan bukan foo.us.com (domain pribadi us.com ditambah label sebelumnya foo).

Catatan: Data akhiran publik dapat berubah dari waktu ke waktu. Akibatnya, input yang menghasilkan nilai kosong default sekarang dapat menghasilkan nilai yang tidak kosong di masa mendatang.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh ini menunjukkan string kosong

strings.extract_domain("") = ""

Contoh 2

string acak, bukan URL

strings.extract_domain("1234") = ""

Contoh 3

beberapa backslach

strings.extract_domain("\\\\") = ""

Contoh 4

karakter non-alfabet ditangani dengan baik

strings.extract_domain("http://例子.卷筒纸.中国") = "卷筒纸.中国"

Contoh 5

menangani URI

strings.extract_domain("mailto:?to=&subject=&body=") = ""

Contoh 6

beberapa karakter sebelum URL sebenarnya

strings.extract_domain("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "google.com"

Contoh 7

karakter khusus dalam URI #

strings.extract_domain("test#@google.com") = ""

Contoh 8

karakter khusus di URL #

strings.extract_domain("https://test#@google.com") = ""

Contoh 9

kasus pengujian positif

strings.extract_domain("https://google.co.in") = "google.co.in"

strings.extract_hostname

Didukung di:

Aturan Penelusuran

strings.extract_hostname(string)

Deskripsi

Mengekstrak nama host dari string. Fungsi ini peka huruf besar/kecil.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh ini menampilkan string kosong.

strings.extract_hostname("") = ""

Contoh 2

string acak, bukan URL

strings.extract_hostname("1234") = "1234"

Contoh 3

beberapa garis miring terbalik

strings.extract_hostname("\\\\") = ""

Contoh 4

karakter non-Inggris ditangani dengan baik

strings.extract_hostname("http://例子.卷筒纸.中国") = "例子.卷筒纸.中国"

Contoh 5

menangani URI

strings.extract_hostname("mailto:?to=&subject=&body=") = "mailto"

Contoh 6

beberapa karakter sebelum URL sebenarnya

strings.extract_hostname("     \t   !$5*^)&dahgsdfs;http://www.google.com") = "www.google.com"

Contoh 7

karakter khusus dalam URI #

strings.extract_hostname("test#@google.com") = "test"

Contoh 8

karakter khusus di URL #

strings.extract_hostname("https://test#@google.com") = "test"

strings.from_hex

Didukung di:

Aturan Penelusuran

strings.from_hex(hex_string)

Deskripsi

Menampilkan byte yang terkait dengan string hex yang diberikan.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

BYTES

Contoh kode

Mendapatkan byte yang terkait dengan string hex tertentu.

Contoh 1

Contoh ini menunjukkan konversi karakter non-hex.

strings.from_hex("str") // returns empty bytes

Contoh 2

Contoh ini menunjukkan input dengan string kosong.

strings.from_hex("") // returns empty bytes

Contoh 3

Contoh ini menunjukkan konversi string hex.

strings.from_hex("1234") // returns 1234 bytes

Contoh 4

Contoh ini menunjukkan konversi karakter non-ASCII.

strings.from_hex("筒纸.中国") // returns empty bytes

strings.ltrim

Didukung di:

Aturan Penelusuran

strings.ltrim(string_to_trim, cutset)

Deskripsi

Memangkas spasi kosong di awal dari string tertentu. Fungsi ini menghapus karakter awal yang ada dalam cutset tersebut.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Berikut adalah contoh kasus penggunaan.

Contoh 1

Contoh ini menggunakan argumen pertama dan kedua yang sama.

strings.ltrim("str", "str") = ""

Contoh 2

Contoh ini menggunakan string kosong sebagai argumen kedua.

strings.ltrim("str", "") = "str"

Contoh 3

Contoh ini menggunakan string kosong sebagai argumen pertama, dan string sebagai argumen kedua.

strings.ltrim("", "str") = ""

Contoh 4

Contoh ini menggunakan string yang berisi spasi kosong, dan string sebagai argumen kedua.

strings.ltrim("a aastraa aa ", " a") = "straa aa "

strings.reverse

Didukung di:

Aturan Penelusuran

strings.reverse(STRING)

Deskripsi

Menampilkan string yang merupakan kebalikan dari string input.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut meneruskan string singkat.

strings.reverse("str") = "rts"  // The function returns 'rts'.

Contoh 2

Contoh berikut meneruskan string kosong.

strings.reverse("") = ""

Contoh 3

Contoh berikut meneruskan palindrome.

strings.reverse("tacocat") = "tacocat"

strings.rtrim

Didukung di:

Aturan Penelusuran

strings.rtrim(string_to_trim, cutset)

Deskripsi

Memangkas spasi kosong di akhir dari string tertentu. Menghapus karakter di akhir yang ada dalam cutset tersebut.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Berikut adalah contoh kasus penggunaan.

Contoh 1

Contoh berikut meneruskan string yang sama dengan argumen pertama dan kedua.

strings.rtrim("str", "str") = ""

Contoh 2

Contoh berikut meneruskan string kosong sebagai argumen kedua.

strings.rtrim("str", "") = "str"

Contoh 3

Contoh berikut meneruskan string kosong sebagai argumen pertama dan string yang tidak kosong sebagai argumen kedua.

strings.rtrim("", "str") = ""

Contoh 4

Contoh berikut meneruskan string yang berisi spasi kosong sebagai argumen pertama dan string yang tidak kosong sebagai argumen kedua.

strings.rtrim("a aastraa aa ", " a") = "a aasstr"

strings.to_lower

Didukung di:

Aturan Penelusuran

strings.to_lower(stringText)

Deskripsi

Fungsi ini mengambil string input dan menampilkan string setelah mengubah semua karakter menjadi huruf kecil

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut menampilkan true.

"[e-mail]" = strings.to_lower($e.network.email.to)

strings.to_upper

Didukung di:

Aturan Penelusuran

strings.to_upper(string_val)

Deskripsi

Menampilkan string asli dengan semua karakter alfabet dalam huruf besar.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh berikut menampilkan argumen yang diberikan dalam huruf besar.

strings.to_upper("example") = "EXAMPLE"

strings.trim

Didukung di:

Aturan Penelusuran

strings.trim(string_to_trim, cutset)

Deskripsi

Memangkas spasi kosong di awal dan di akhir dari string tertentu. Selain itu, hapus karakter yang tidak diinginkan (ditentukan oleh argumen cutset) dari string input.

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Berikut adalah contoh kasus penggunaan.

Contoh 1

Dalam contoh berikut, string yang sama diteruskan sebagai string input dan cutset, yang menghasilkan string kosong.

strings.trim("str", "str") // ""

Contoh 2

Dalam contoh berikut, string kosong diteruskan sebagai cutset, yang menghasilkan string asli str karena tidak ada karakter yang ditentukan dalam cutset untuk dihapus.

strings.trim("str", "") = "str"

Contoh 3

Dalam contoh berikut, fungsi menghasilkan string kosong karena string input sudah kosong dan tidak ada karakter yang akan dihapus.

strings.trim("", "str") = ""

Contoh 4

Dalam contoh berikut, fungsi menghasilkan str karena fungsi trim menghapus hal berikut:

• spasi kosong di akhir "a aastraa aa "
• karakter yang ditentukan dalam cutset (spasi, a)

strings.trim("a aastraa aa ", " a") = "str"

strings.url_decode

Didukung di:

Aturan Penelusuran

strings.url_decode(url_string)

Deskripsi

Dengan string URL, dekode karakter escape dan tangani karakter UTF-8 yang telah dienkode. Menampilkan string kosong jika decoding gagal.

Jenis data parameter

STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Contoh ini menunjukkan kasus pengujian positif.

strings.url_decode("three%20nine%20four") = "three nine four"

Contoh 2

Contoh ini menunjukkan kasus string kosong.

strings.url_decode("") // ""

Contoh 3

Contoh ini menunjukkan penanganan karakter non-alfabet.

strings.url_decode("%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B") // "上海+中國"

Contoh 4

Contoh ini menunjukkan contoh decoding URL.

strings.url_decode("http://www.google.com%3Fparam1%3D%22+1+%3E+2+%22%26param2%3D2%3B") // 'http://www.google.com?param1="+1+>+2+"&param2=2;'

timestamp.as_unix_seconds

Didukung di:

Aturan Penelusuran

timestamp.as_unix_seconds(timestamp [, time_zone])

Deskripsi

Fungsi ini menampilkan bilangan bulat yang mewakili jumlah detik setelah epoch Unix untuk string stempel waktu yang diberikan.

• timestamp adalah string yang mewakili stempel waktu epoch yang valid. Formatnya harus %F %T.
• time_zone bersifat opsional dan merupakan string yang mewakili zona waktu. Jika dihilangkan, defaultnya adalah GMT. Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah sebagai berikut:
  • Nama database TZ, misalnya America/Los_Angeles. Untuk mengetahui informasi selengkapnya, lihat daftar zona waktu database tz di Wikipedia.
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

STRING, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Stempel waktu epoch yang valid

timestamp.as_unix_seconds("2024-02-22 10:43:00") = 1708598580

Contoh 2

Stempel waktu epoch yang valid dengan zona waktu America/New_York

timestamp.as_unix_seconds("2024-02-22 10:43:00", "America/New_York") = 1708616580

timestamp.current_seconds

Didukung di:

Aturan Penelusuran

timestamp.current_seconds()

Deskripsi

Menampilkan bilangan bulat yang mewakili waktu saat ini dalam detik Unix. Nilai ini hampir sama dengan stempel waktu deteksi dan didasarkan pada waktu aturan dijalankan. Fungsi ini adalah sinonim dari fungsi timestamp.now().

Jenis data parameter

NONE

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Contoh berikut menampilkan true jika masa berlaku sertifikat telah berakhir lebih dari 24 jam. Fungsi ini menghitung perbedaan waktu dengan mengurangi detik Unix saat ini, lalu membandingkannya menggunakan operator lebih besar dari.

86400 < timestamp.current_seconds() - $e.network.tls.certificate.not_after

timestamp.get_date

Didukung di:

Aturan Penelusuran

timestamp.get_date(unix_seconds [, time_zone])

Deskripsi

Fungsi ini menampilkan string dalam format YYYY-MM-DD, yang mewakili hari stempel waktu.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• time_zone bersifat opsional dan merupakan string yang mewakili time_zone. Jika dihilangkan, defaultnya adalah "GMT". Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah:
  • Nama database TZ, misalnya "America/Los_Angeles". Untuk informasi selengkapnya, lihat kolom"Nama Database TZ" dari halaman ini
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts) = "2024-02-19"

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_date($ts, "America/Los_Angeles") = "2024-02-20"

timestamp.get_minute

Didukung di:

Aturan Penelusuran

timestamp.get_minute(unix_seconds [, time_zone])

Deskripsi

Fungsi ini menampilkan bilangan bulat dalam rentang [0, 59] yang mewakili menit.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• time_zone bersifat opsional dan merupakan string yang mewakili zona waktu. Jika dihilangkan, defaultnya adalah "GMT". Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah:
  • Nama database TZ, misalnya "America/Los_Angeles". Untuk informasi selengkapnya, lihat kolom"Nama Database TZ" dari halaman ini
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_hour

Didukung di:

Aturan Penelusuran

timestamp.get_hour(unix_seconds [, time_zone])

Deskripsi

Fungsi ini menampilkan bilangan bulat dalam rentang [0, 23] yang mewakili jam.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• time_zone bersifat opsional dan merupakan string yang mewakili zona waktu. Jika dihilangkan, defaultnya adalah "GMT". Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah:
  • Nama database TZ, misalnya "America/Los_Angeles". Untuk informasi selengkapnya, lihat kolom"Nama Database TZ" dari halaman ini
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts) = 15

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_hour($ts, "America/Los_Angeles") = 15

timestamp.get_day_of_week

Didukung di:

Aturan Penelusuran

timestamp.get_day_of_week(unix_seconds [, time_zone])

Deskripsi

Fungsi ini menampilkan bilangan bulat dalam rentang [1, 7] yang mewakili hari dalam seminggu yang dimulai dengan hari Minggu. Misalnya, 1 = Minggu dan 2 = Senin.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• time_zone bersifat opsional dan merupakan string yang mewakili time_zone. Jika dihilangkan, defaultnya adalah "GMT". Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah:
  • Nama database TZ, misalnya "America/Los_Angeles". Untuk informasi selengkapnya, lihat kolom"Nama Database TZ" dari halaman ini
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts) = 6

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_day_of_week($ts, "America/Los_Angeles") = 6

timestamp.get_timestamp

Didukung di:

Aturan Penelusuran

timestamp.get_timestamp(unix_seconds, optional timestamp_format, optional timezone)

Deskripsi

Fungsi ini menampilkan string dalam format YYYY-MM-DD, yang mewakili hari stempel waktu.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• timestamp_format bersifat opsional dan merupakan string yang mewakili format untuk stempel waktu. Jika dihilangkan, defaultnya adalah %F %T. Anda dapat menentukan format menggunakan literal string. Untuk mengetahui opsi, lihat Memformat elemen untuk bagian tanggal dan waktu
• time_zone bersifat opsional dan merupakan string yang mewakili zona waktu. Jika dihilangkan, defaultnya adalah GMT. Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah sebagai berikut:
  • Nama database Zona Waktu (TZ) IANA, misalnya, America/Los_Angeles. Untuk informasi selengkapnya, lihat daftar zona waktu database tz di Wikipedia.
  • Offset zona waktu dari UTC, dalam format (+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah GMT.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts) = "2024-02-22 10:43:51"

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%F %T", "America/Los_Angeles") = "2024-02-22 10:43:51"

Contoh 3

Contoh ini menggunakan literal string untuk menentukan timestamp_format.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_timestamp($ts, "%Y-%m", "GMT") = "2024-02"

timestamp.get_week

Didukung di:

Aturan Penelusuran

timestamp.get_week(unix_seconds [, time_zone])

Deskripsi

Fungsi ini menampilkan bilangan bulat dalam rentang [0, 53] yang mewakili minggu dalam tahun. Minggu dimulai pada hari Minggu. Tanggal sebelum hari Minggu pertama dalam suatu tahun berada di minggu 0.

• unix_seconds adalah bilangan bulat yang mewakili jumlah detik setelah epoch Unix, seperti $e.metadata.event_timestamp.seconds, atau placeholder yang berisi nilai tersebut.
• time_zone bersifat opsional dan merupakan string yang mewakili zona waktu. Jika dihilangkan, defaultnya adalah "GMT". Anda dapat menentukan zona waktu menggunakan literal string. Opsi yang tersedia adalah:
  • Nama database TZ, misalnya "America/Los_Angeles". Untuk informasi selengkapnya, lihat kolom"Nama Database TZ" dari halaman ini
  • Offset zona waktu dari UTC, dalam format(+|-)H[H][:M[M]], misalnya: "-08:00".

Berikut adalah contoh penentu time_zone yang valid, yang dapat Anda teruskan sebagai argumen kedua ke fungsi ekstraksi waktu:

"America/Los_Angeles", or "-08:00". ("PST" is not supported)
"America/New_York", or "-05:00". ("EST" is not supported)
"Europe/London"
"UTC"
"GMT"

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Dalam contoh ini, argumen time_zone dihilangkan, sehingga default-nya adalah "GMT".

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts) = 0

Contoh 2

Contoh ini menggunakan literal string untuk menentukan time_zone.

$ts = $e.metadata.collected_timestamp.seconds

timestamp.get_week($ts, "America/Los_Angeles") = 0

timestamp.now

Didukung di:

Aturan Penelusuran

timestamp.now()

Deskripsi

Menampilkan jumlah detik sejak 1970-01-01 00:00:00 UTC. Hal ini juga dikenal sebagai waktu epoch Unix.

Jenis hasil yang ditampilkan

INT

Contoh kode

Contoh 1

Contoh berikut menampilkan stempel waktu untuk kode yang dieksekusi pada 22 Mei 2024 pukul 18.16.59.

timestamp.now() = 1716401819 // Unix epoch time in seconds for May 22, 2024 at 18:16:59

window.avg

Didukung di:

Aturan

window.avg(numeric_values [, should_ignore_zero_values])

Deskripsi

Menampilkan rata-rata nilai input (yang dapat berupa Bilangan Bulat atau Float). Menetapkan argumen kedua opsional ke true akan mengabaikan nilai nol.

Jenis data parameter

INT|FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menunjukkan rata-rata bilangan bulat.

// This rule sets the outcome $size_mode to the average
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 2.5 if the event file size values in the match window are 1, 2, 3 and 4

Contoh 2

Contoh ini menunjukkan rata-rata float.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 1.75 if the event file size values in the match window are 1.1 and 2.4

Contoh 3

Rata-rata input negatif

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0.6 if the event file size values in the match window are -1.1, 1.1, 0.0 and 2.4

Contoh 4

0 menampilkan 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size) // yields 0 if the event file size values in the match window is 0

Contoh 5

Mengabaikan nilai 0

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.avg($e.file.size, true) // yields 394 if the event file size values in the match window are 0, 0, 0 and 394

window.first

Didukung di:

Aturan

window.first(values_to_sort_by, values_to_return)

Deskripsi

Fungsi agregasi ini menampilkan nilai string yang berasal dari peristiwa dengan nilai int berkorelasi terendah dalam periode pencocokan. Contoh kasus penggunaan adalah mendapatkan user-id dari peristiwa dengan stempel waktu terendah dalam periode pencocokan (peristiwa paling awal).

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Mendapatkan nilai string yang berasal dari peristiwa dengan nilai int berkorelasi terendah dalam periode pencocokan.

// This rule sets the outcome $first_event to the lowest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $first_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v1 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.last

Didukung di:

Aturan

window.last(values_to_sort_by, values_to_return)

Deskripsi

Fungsi agregasi ini menampilkan nilai string yang berasal dari peristiwa dengan nilai int berkorelasi tertinggi dalam periode pencocokan. Contoh kasus penggunaan adalah mendapatkan user-id dari peristiwa dengan stempel waktu terendah dalam periode pencocokan (stempel waktu tertinggi).

Jenis data parameter

INT, STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Mendapatkan nilai string yang berasal dari peristiwa dengan nilai int berkorelasi tertinggi dalam periode pencocokan.

// This rule sets the outcome $last_event to the highest correlated int value
// in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $last_event = window.first($e.metadata.timestamp.seconds, $e.metadata.event_type) // yields v3 if the events in the match window are 1, 2 and 3 and corresponding values v1, v2, and v3.

window.median

Didukung di:

Aturan

window.median(numeric_values, should_ignore_zero_values)

Deskripsi

Menampilkan median nilai input. Jika ada 2 nilai median, hanya 1 yang akan dipilih secara non-deterministik sebagai nilai yang ditampilkan.

Jenis data parameter

INT|FLOAT, BOOL

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menampilkan median saat nilai input bukan nol.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 2 if the file sizes in the match window are [1, 2, 3]
  condition:
      $e
}

Contoh 2

Contoh ini menampilkan median saat input menyertakan beberapa nilai nol yang tidak boleh diabaikan.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Contoh 3

Contoh ini menampilkan median saat input menyertakan beberapa nilai nol yang harus diabaikan.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size, true) // returns 2 if the file sizes in the match window are [0,0, 1, 2, 3]
  condition:
      $e
}

Contoh 4

Contoh ini menampilkan median saat input menyertakan semua nilai nol yang harus diabaikan.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 0 if the file sizes in the match window are [0,0]
  condition:
      $e
}

Contoh 5

Contoh ini menunjukkan bahwa, jika ada beberapa median, hanya satu median yang ditampilkan.

rule median_file_size {
    meta:
    events:
      $e.metadata.event_type = "FILE_COPY"
        $userid = $e.principal.user.userid
    match:
      $userid over 1h
    outcome:
      $median_file_size = window.median($e.principal.file.size) // returns 1 if the file sizes in the match window are [1, 2, 3, 4]
  condition:
      $e
}

window.mode

Didukung di:

Aturan

window.mode(values)

Deskripsi

Menampilkan mode nilai input. Jika ada beberapa kemungkinan nilai mode, hanya satu dari nilai tersebut yang akan dipilih secara non-deterministik sebagai nilai yang ditampilkan.

Jenis data parameter

INT|FLOAT|STRING

Jenis hasil yang ditampilkan

STRING

Contoh kode

Contoh 1

Mendapatkan mode nilai di jendela pencocokan.

// This rule sets the outcome $size_mode to the most frequently occurring
// file size in the 5 minute match window.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $size_mode = window.mode($e.file.size) // yields 1.6 if the event file size values in the match window are 1.6, 2, and 1.6

window.stddev

Didukung di:

Aturan

window.stddev(numeric_values)

Deskripsi

Menampilkan simpangan baku nilai input dalam jendela kecocokan.

Jenis data parameter

INT|FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menampilkan simpangan baku bilangan bulat dalam periode pencocokan.

// This rule creates a detection when the file size stddev in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.0 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 2

Contoh 2

Contoh ini menampilkan simpangan baku float dalam jendela pencocokan.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 4.488686 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 2

Contoh 3

Contoh ini menampilkan simpangan baku dalam periode pencocokan yang berisi angka negatif.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 48.644972 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 2

Contoh 4

Contoh ini ditampilkan dengan simpangan baku nol jika semua nilai dalam periode pencocokan sama.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 2

Contoh 5

Contoh ini menampilkan simpangan baku periode pencocokan yang berisi angka positif dan negatif.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.stddev($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

window.variance

Didukung di:

Aturan

window.variance(values)

Deskripsi

Fungsi ini menampilkan varians nilai input yang ditentukan.

Jenis data parameter

INT|FLOAT

Jenis hasil yang ditampilkan

FLOAT

Contoh kode

Contoh 1

Contoh ini menampilkan varians dari semua bilangan bulat.

// This rule creates a detection when the file size variance in 5 minutes for a user is over a threshold.
events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 16 if the event file size values in the match window are [10, 14, 18].
condition:
  $e and #p1 > 10

Contoh 2

Contoh ini menampilkan varians semua float.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 20.148300 if the event file size values in the match window are [10.00, 14.80, 18.97].
condition:
  $e and #p1 > 10

Contoh 3

Contoh ini menampilkan variansi angka negatif.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 2366.333333 if the event file size values in the match window are [-1, -56, -98].
condition:
  $e and #p1 > 10

Contoh 4

Contoh ini menampilkan nilai varians kecil.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [0.000000, 0.000000, 0.000100].
condition:
  $e and #p1 > 10

Contoh 5

Contoh ini menampilkan varians nol.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 0.000000 if the event file size values in the match window are [1, 1, 1].
condition:
  $e and #p1 > 10

Contoh 6

Contoh ini menampilkan varians bilangan positif dan negatif.

events:
 $e.user.userid = $userid
match:
 $userid over 5m
outcome:
  $p1 = window.variance($e.file.size) // yields 1.000000 if the event file size values in the match window are [1, 0, -1].
condition:
  $e and #p1 > 10

Penetapan fungsi ke placeholder

Anda dapat menetapkan hasil panggilan fungsi ke placeholder di bagian events. Contoh:

$placeholder = strings.concat($e.principal.hostname, "my-string").

Kemudian, Anda dapat menggunakan variabel placeholder di bagian match, condition, dan outcome. Namun, ada dua batasan dengan penetapan fungsi ke placeholder:

1. Setiap placeholder dalam fungsi ke penetapan placeholder harus ditetapkan ke ekspresi yang berisi kolom peristiwa. Misalnya, contoh berikut valid:

   $ph1 = $e.principal.hostname
   $ph2 = $e.src.hostname
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.concat($ph2, ".com")
   

   $ph1 = $e.network.email.from
   $ph2 = strings.concat($e.principal.hostname, "@gmail.com")
   
   // Both $ph1 and $ph2 have been assigned to an expression containing an event field.
   $ph1 = strings.to_lower($ph2)
   

   Namun, contoh berikut tidak valid:

   $ph1 = strings.concat($e.principal.hostname, "foo")
   $ph2 = strings.concat($ph1, "bar") // $ph2 has NOT been assigned to an expression containing an event field.
   

2. Panggilan fungsi harus bergantung pada satu dan tepat satu peristiwa. Namun, lebih dari satu kolom dari peristiwa yang sama dapat digunakan dalam argumen panggilan fungsi. Misalnya, hal berikut valid:

   $ph = strings.concat($event.principal.hostname, "string2")

   $ph = strings.concat($event.principal.hostname, $event.src.hostname)

   Namun, hal berikut tidak valid:

   $ph = strings.concat("string1", "string2")

   $ph = strings.concat($event.principal.hostname, $anotherEvent.src.hostname)

Sintaksis Daftar Referensi

Lihat halaman Daftar Referensi untuk mengetahui informasi selengkapnya tentang perilaku daftar referensi dan sintaksis daftar referensi.

Anda dapat menggunakan daftar referensi di bagian events atau outcome. Berikut adalah sintaksis untuk menggunakan berbagai jenis daftar referensi dalam aturan:

// STRING reference list
$e.principal.hostname in %string_reference_list

// REGEX reference list
$e.principal.hostname in regex %regex_reference_list

// CIDR reference list
$e.principal.ip in cidr %cidr_reference_list

Anda juga dapat menggunakan operator not dan operator nocase dengan daftar referensi seperti yang ditunjukkan dalam contoh berikut:

// Exclude events whose hostnames match substrings in my_regex_list.
not $e.principal.hostname in regex %my_regex_list

// Event hostnames must match at least 1 string in my_string_list (case insensitive).
$e.principal.hostname in %my_string_list nocase

Operator nocase kompatibel dengan daftar STRING dan daftar REGEX.

Untuk alasan performa, Mesin Deteksi membatasi penggunaan daftar referensi.

• Pernyataan in maksimum dalam aturan, dengan atau tanpa operator khusus: 7
• Pernyataan in maksimum dengan operator regex: 4
• Pernyataan in maksimum dengan operator cidr: 2

Pemeriksaan jenis

Google Security Operations melakukan pemeriksaan jenis terhadap sintaksis YARA-L saat Anda membuat aturan dalam antarmuka. Error pemeriksaan jenis yang ditampilkan membantu Anda merevisi aturan sedemikian rupa untuk memastikan bahwa aturan tersebut akan berfungsi seperti yang diharapkan.

Berikut adalah contoh predikat tidak valid:

// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"

// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"

Pengambilan Sampel Peristiwa Deteksi

Deteksi dari aturan multi-peristiwa berisi sampel peristiwa untuk memberikan konteks tentang peristiwa yang menyebabkan deteksi. Ada batas hingga 10 sampel peristiwa untuk setiap variabel peristiwa yang ditentukan dalam aturan. Misalnya, jika aturan menentukan 2 variabel peristiwa, setiap deteksi dapat memiliki maksimal 20 sampel peristiwa. Batas ini berlaku untuk setiap variabel peristiwa secara terpisah. Jika satu variabel peristiwa memiliki 2 peristiwa yang berlaku dalam deteksi ini, dan variabel peristiwa lainnya memiliki 15 peristiwa yang berlaku, deteksi yang dihasilkan akan berisi 12 sampel peristiwa (2 + 10).

Setiap sampel peristiwa yang melebihi batas akan dihilangkan dari deteksi.

Jika menginginkan informasi selengkapnya tentang peristiwa yang menyebabkan deteksi, Anda dapat menggunakan agregasi di bagian hasil untuk menghasilkan informasi tambahan dalam deteksi.

Jika melihat deteksi di UI, Anda dapat mendownload semua sampel peristiwa untuk deteksi. Untuk informasi selengkapnya, lihat Mendownload peristiwa.