YARA-L 2.0 言語の概要

以下でサポートされています。

Google SecOpsSIEM

YARA-L 2.0 は、エンタープライズログデータを Google Security Operations インスタンスに取り込んで検索する際のルールの作成に使用されるコンピュータ言語です。YARA-L 構文は、VirusTotal が開発した YARA 言語から派生しています。この言語は Google Security Operations Detection Engine と組み合わせて動作し、大量のデータ全体で脅威などのイベントを検出できます。

詳しくは以下をご覧ください。

YARA-L 2.0 のルールの例

次の例は、YARA-L 2.0 で書かれたルールを示しています。それぞれは、ルール言語内でイベントを相関させる方法を示しています。

ルールとチューニング

次のルールは、イベントデータ内の特定のパターンをチェックし、パターンが見つかった場合に検出を作成します。このルールには、イベントタイプと metadata.event_type UDM フィールドを追跡するための変数 $e1 が含まれています。このルールは、e1 と一致する正規表現の特定の出現をチェックします。イベント $e1 が発生すると、検出が作成されます。特定の悪意のないパスを除外するために、ルールに not 条件が含まれています。not 条件を追加して、誤検知を防ぐことができます。

rule suspicious_unusual_location_svchost_execution
{

 meta:
   author = "Google Cloud Security"
   description = "Windows 'svchost' executed from an unusual location"
   yara_version = "YL2.0"
   rule_version = "1.0"

 events:

   $e1.metadata.event_type = "PROCESS_LAUNCH"
   re.regex($e1.principal.process.command_line, `\bsvchost(\.exe)?\b`) nocase
   not re.regex($e1.principal.process.command_line, `\\Windows\\System32\\`) nocase

condition:

   $e1
}

異なる都市からのログイン

次のルールは、2 つ以上の都市から 5 分以内に企業にログインしたユーザーを検索します。

rule DifferentCityLogin {
  meta:

  events:
    $udm.metadata.event_type = "USER_LOGIN"
    $udm.principal.user.userid = $user
    $udm.principal.location.city = $city

  match:
    $user over 5m

  condition:
    $udm and #city > 1
}

変数に一致: $user

Event 変数:$udm

プレースホルダ変数: $city、$user

このルールの仕組みは次のとおりです。

ユーザー名（$user）を持つイベントをグループ化し、一致するものが見つかったらそれ（$user）を返します。
期間は 5 分です。これは、5 分未満の間隔のイベントどうしのみが関連付けられることを意味します。
イベントタイプが USER_LOGIN のイベントグループ（$udm）を検索します。
そのイベントグループについて、ルールはユーザー ID を $user として、ログインの都市を $city. として呼び出します。
5 分間以内にイベントグループ（$udm）で city 値の固有の数（#city で示される）が 1 より大きい場合に一致を返します。

迅速なユーザーの作成と削除

次のルールは、4 時間以内に作成され、削除されたユーザーを検索します。

rule UserCreationThenDeletion {
  meta:

  events:
    $create.target.user.userid = $user
    $create.metadata.event_type = "USER_CREATION"

    $delete.target.user.userid = $user
    $delete.metadata.event_type = "USER_DELETION"

    $create.metadata.event_timestamp.seconds <=
       $delete.metadata.event_timestamp.seconds

  match:
    $user over 4h

  condition:
    $create and $delete
}

Event 変数:$create および $delete

変数に一致: $user

プレースホルダ変数: 該当なし

このルールの仕組みは次のとおりです。

ユーザー名（$user）を持つイベントをグループ化し、一致するものが見つかったらそれ（$user）を返します。
時間枠は 4 時間です。これは、4 時間未満のイベントのみが関連付けられることを意味します。
2 つのイベントグループを検索します（$create と $delete。$create は #create >= 1 と同等）。
$create は USER_CREATION イベントに対応しており、ユーザー ID を $user として呼び出します。
$user は 2 つのイベントグループを結合するために使用されます。
$delete は USER_DELETION イベントに対応しており、ユーザー ID を $user として呼び出します。このルールは、2 つのイベントグループのユーザー ID が同じ一致を検索します。
このルールは、$delete のイベントが $create のイベントより後で発生した場合を検索し、見つかったときに一致を返します。

単一イベントルール

単一イベントルールは、1 つのイベントに関連するルールです。単一イベントルールを次のように指定できます。

一致セクションがないルール。
match セクションと condition セクションで、1 つのイベントが存在するかどうかのみを確認するルール（例: 「$e」、「#e > 0」、「#e >= 1」、「1 <= #e」、「0 < #e」）。

たとえば、次のルールはユーザーのログインイベントを検索し、Google Security Operations アカウント内に保存された企業データ内で最初に検出されたものを返します。

rule SingleEventRule {
  meta:
    author = "noone@altostrat.com"

  events:
    $e.metadata.event_type = "USER_LOGIN"

  condition:
    $e
}

一致セクションを含む単一イベントルールの別の例を以下に示します。このルールは、5 分以内に 1 回以上ログインしたユーザーを検索します。ユーザーのログインイベントが単に存在するかどうかをチェックします。

rule SingleEventRule {
  meta:
    author = "alice@example.com"
    description = "windowed single event example rule"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 5m

  condition:
    #e > 0
}

rule MultiEventRule{
  meta:
    author = "alice@example.com"
    description = "Rule with outcome condition and simple existence condition on one event variable"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 10m

  outcome:
    $num_events_in_match_window = count($e.metadata.id)

  condition:
    #e > 0 and $num_events_in_match_window >= 10 // Could be rewritten as #e >= 10
}

マルチイベントのルール

マルチイベントルールを使用して、特定の期間に多くのイベントをグループ化し、イベント間の相関関係の特定を試みます。一般的なマルチイベントルールは次のようになります。

イベントをグループ化する期間を指定する　match　セクション。
検出をトリガーし、複数のイベントの存在を確認する条件を指定する　condition　セクション。

たとえば、次のルールは、10 分以内に最低 10 回以上ログインしたユーザーを検索します。

rule MultiEventRule {
  meta:
    author = "noone@altostrat.com"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.principal.user.userid = $user

  match:
    $user over 10m

  condition:
    #e >= 10
}

IP アドレスの範囲内での単一イベント

次の例は、2 つの特定のユーザーと特定の IP アドレス範囲との一致を検索する単一のイベントルールを示しています。

rule OrsAndNetworkRange {
  meta:
    author = "noone@altostrat.com"

  events:
    // Checks CIDR ranges.
    net.ip_in_range_cidr($e.principal.ip, "203.0.113.0/24")

    // Detection when the hostname field matches either value using or.
    $e.principal.hostname = /pbateman/ or $e.principal.hostname = /sspade/

  condition:
    $e
}

any と all のルールの例

次のルールは、すべての発信元 IP アドレスが 5 分以内に安全であるとわかっている IP アドレスと一致しないログインイベントを検索します。

rule SuspiciousIPLogins {
  meta:
    author = "alice@example.com"

  events:
    $e.metadata.event_type = "USER_LOGIN"

    // Detects if all source IP addresses in an event do not match "100.97.16.0"
    // For example, if an event has source IP addresses
    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
    // it will be detected since "100.97.16.1", "100.97.16.2",
    // and "100.97.16.3" all do not match "100.97.16.0".

    all $e.principal.ip != "100.97.16.0"

    // Assigns placeholder variable $ip to the $e.principal.ip repeated field.
    // There will be one detection per source IP address.
    // For example, if an event has source IP addresses
    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
    // there will be one detection per address.

    $e.principal.ip = $ip

  match:
    $ip over 5m

  condition:
    $e
}

ルール内の正規表現

次の YARA-L 2.0 正規表現の例では、match.com ドメインから受信したメールで、イベントを検索します。nocase が $host 変数の regex 比較と regex 関数に追加されたため、これらの比較では大文字と小文字が区別されません。

rule RegexRuleExample {
  meta:
    author = "noone@altostrat.com"

  events:
    $e.principal.hostname = $host
    $host = /.*HoSt.*/ nocase
    re.regex($e.network.email.from, `.*altostrat\.com`) nocase

  match:
    $host over 10m

  condition:
    #e > 10
}

スライディングウィンドウのルールの例

次の YARA-L 2.0 スライディングウィンドウの例では、firewall_1 イベントの後で firewall_2 イベントが欠落していることを検索します。after キーワードは、ピボットイベント変数 $e1 と併用され、イベントを関連付ける際にチェックを行う必要がある時間枠として、各 firewall_1 イベントの後に 10 分間のみの時間枠を指定します。

rule SlidingWindowRuleExample {
  meta:
    author = "alice@example.com"

  events:
    $e1.metadata.product_name = "firewall_1"
    $e1.principal.hostname = $host

    $e2.metadata.product_name = "firewall_2"
    $e2.principal.hostname = $host

  match:
    $host over 10m after $e1

  condition:
    $e1 and !$e2
}

ゼロ値除外の例

ルールエンジンは、match セクションで使用されているすべてのプレースホルダのゼロ値を暗黙的に除外します。詳細については、match セクションのゼロ値の処理をご覧ください。これは、allow_zero_values で説明されているように allow_zero_values オプションを使用して無効にできます。

ただし、参照される他のイベントフィールドでは、そのような条件を明示的に指定しない限り、ゼロ値は除外されません。

rule ExcludeZeroValues {
  meta:
    author = "alice@example.com"

  events:
    $e1.metadata.event_type = "NETWORK_DNS"
    $e1.principal.hostname = $hostname

    // $e1.principal.user.userid may be empty string.
    $e1.principal.user.userid != "Guest"

    $e2.metadata.event_type = "NETWORK_HTTP"
    $e2.principal.hostname = $hostname

    // $e2.target.asset_id cannot be empty string as explicitly specified.
    $e2.target.asset_id != ""

  match:
    // $hostname cannot be empty string. The rule behaves as if the
    // predicate, `$hostname != ""` was added to the events section, because
    // `$hostname` is used in the match section.
    $hostname over 1h

  condition:
    $e1 and $e2
}

`outcome` セクションを含むルールの例

YARA-L 2.0 ルールにオプションの outcome セクションを追加して、各検出の追加情報を抽出できます。条件セクションで、結果変数に条件を指定することもできます。検出ルールの outcome セクションを使用して、ダウンストリームでの消費のための変数を設定できます。たとえば、分析対象のイベントからのデータに基づいて重大度スコアを設定できます。

詳しくは以下をご覧ください。

結果セクションを含むマルチイベントルール:

次のルールは、2 つのイベントを調べて $hostname の値を取得します。$hostname の値が 5 分間を超えて一致した場合、重大度スコアが適用されます。match セクションに期間を含めると、ルールは指定された期間内でチェックされます。

rule OutcomeRuleMultiEvent {
    meta:
      author = "Google Cloud Security"
    events:
      $u.udm.principal.hostname = $hostname
      $asset_context.graph.entity.hostname = $hostname

      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity

    match:
      $hostname over 5m

    outcome:
      $risk_score =
        max(
            100
          + if($hostname = "my-hostname", 100, 50)
          + if($severity = "HIGH", 10)
          + if($severity = "MEDIUM", 5)
          + if($severity = "LOW", 1)
        )

      $asset_id_list =
        array(
          if($u.principal.asset_id = "",
             "Empty asset id",
             $u.principal.asset_id
          )
        )

      $asset_id_distinct_list = array_distinct($u.principal.asset_id)

      $asset_id_count = count($u.principal.asset_id)

      $asset_id_distinct_count = count_distinct($u.principal.asset_id)

    condition:
      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
}

rule OutcomeRuleMultiEvent {
    meta:
      author = "alice@example.com"
    events:
      $u.udm.principal.hostname = $hostname
      $asset_context.graph.entity.hostname = $hostname

      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity

    match:
      $hostname over 5m

    outcome:
      $total_network_bytes = sum($u.network.sent_bytes) + sum($u.network.received_bytes)

      $risk_score = if(total_network_bytes > 1024, 100, 50) + 
        max(
          if($severity = "HIGH", 10)
          + if($severity = "MEDIUM", 5)
          + if($severity = "LOW", 1)
        )

      $asset_id_list =
        array(
          if($u.principal.asset_id = "",
             "Empty asset id",
             $u.principal.asset_id
          )
        )

      $asset_id_distinct_list = array_distinct($u.principal.asset_id)

      $asset_id_count = count($u.principal.asset_id)

      $asset_id_distinct_count = count_distinct($u.principal.asset_id)

    condition:
      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
}

結果セクションを含む単一イベントルール:

rule OutcomeRuleSingleEvent {
    meta:
        author = "alice@example.com"
    events:
        $u.metadata.event_type = "FILE_COPY"
        $u.principal.file.size = $file_size
        $u.principal.hostname = $hostname

    outcome:
        $suspicious_host = $hostname
        $admin_severity = if($u.principal.userid in %admin_users, "SEVERE", "MODERATE")
        $severity_tag = if($file_size > 1024, $admin_severity, "LOW")

    condition:
        $u
}

マルチイベントの結果ルールを単一イベントの結果ルールにリファクタリングする。

outcome セクションは、単一イベントルール（match セクションのないルール）とマルチイベントルール（match セクションのルール）の両方に使用できます。結果セクションを使用できるようにマルチイベントとして以前に設計したルールがある場合は、必要に応じてそれらのルールをリファクタリングして match セクションを削除して、パフォーマンスを改善できます。ルールにグループ化を適用する match セクションがなくなったため、より多くの検出項目が表示されることがありますので注意してください。このリファクタリングは、次の例に示すように、1 つのイベント変数を使用するルールでのみ可能です。

イベント変数を 1 つだけ使用するマルチイベント結果ルール（リファクタリングの候補）。

rule OutcomeMultiEventPreRefactor {
    meta:
      author = "alice@example.com"
      description = "Outcome refactor rule, before the refactor"

    events:
      $u.udm.principal.hostname = $hostname

    match:
      $hostname over 5m

    outcome:
      $risk_score = max(if($hostname = "my-hostname", 100, 50))

    condition:
      $u
}

match　セクションを削除することで、ルールをリファクタリングできます。また、ルールは単一イベントになるため、outcome　セクションの集計も削除する必要があります。集計の詳細については、結果の集計をご覧ください。

rule OutcomeSingleEventPostRefactor {
    meta:
      author = "alice@example.com"
      description = "Outcome refactor rule, after the refactor"

    events:
      $u.udm.principal.hostname = $hostname

    // We deleted the match section.

    outcome:
      // We removed the max() aggregate.
      $risk_score = if($hostname = "my-hostname", 100, 50)

    condition:
      $u
}

関数からプレースホルダへのルールの例

プレースホルダ変数は関数呼び出しの結果に割り当てることができます。また、match セクション、outcome セクション、condition セクションなど、ルールの他のセクションでプレースホルダ変数を使用できます。次の例をご覧ください。

rule FunctionToPlaceholderRule {
    meta:
      author = "alice@example.com"
      description = "Rule that uses function to placeholder assignments"

    events:
        $u.metadata.event_type = "EMAIL_TRANSACTION"

        // Use function-placeholder assignment to extract the
        // address from an email.
        // address@website.com -> address
        $email_to_address_only = re.capture($u.network.email.from , "(.*)@")

        // Use function-placeholder assignment to normalize an email:
        // uid@??? -> uid@company.com
        $email_from_normalized = strings.concat(
            re.capture($u.network.email.from , "(.*)@"),
            "@company.com"
        )

        // Use function-placeholder assignment to get the day of the week of the event.
        // 1 = Sunday, 7 = Saturday.
        $dayofweek = timestamp.get_day_of_week($u.metadata.event_timestamp.seconds)

    match:
        // Use placeholder (from function-placeholder assignment) in match section.
        // Group by the normalized from email, and expose it in the detection.
        $email_from_normalized over 5m

    outcome:
        // Use placeholder (from function-placeholder assignment) in outcome section.
        // Assign more risk if the event happened on weekend.
        $risk_score = max(
            if($dayofweek = 1, 10, 0) +
            if($dayofweek = 7, 10, 0)
        )

    condition:
        // Use placeholder (from function-placeholder assignment) in condition section.
        // Match if an email was sent to multiple addresses.
        #email_to_address_only > 1
}

結果条件ルールの例

condition セクションでは、outcome セクションで定義された結果変数を使用できます。次の例では、結果条件を使用して、検出結果内のノイズを軽減するためにリスクスコアでフィルタリングする方法を示します。

rule OutcomeConditionalRule {
    meta:
        author = "alice@example.com"
        description = "Rule that uses outcome conditionals"

    events:
        $u.metadata.event_type = "FILE_COPY"
        $u.principal.file.size = $file_size
        $u.principal.hostname = $hostname

        // 1 = Sunday, 7 = Saturday.
        $dayofweek = timestamp.get_day_of_week($u.metadata.collected_timestamp.seconds)

    outcome:
        $risk_score =
            if($file_size > 500*1024*1024, 2) + // Files 500MB are moderately risky
            if($file_size > 1024*1024*1024, 3) + // Files over 1G get assigned extra risk
            if($dayofweek=1 or $dayofweek=7, 4) + // Events from the weekend are suspicious
            if($hostname = /highly-privileged/, 5) // Check for files from highly privileged devices

    condition:
        $u and $risk_score >= 10
}