スタートガイド: SecOps での YARA-L 2.0

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

Google SecOps SIEM

YARA-L 2.0 は、Google Security Operations のすべての検索、ダッシュボード、ルールベースの脅威検出を強化する独自の高度に構造化されたクエリ言語です。このドキュメントは、セキュリティアナリストが脅威を検出する場合でも、検出エンジニアが堅牢な新しいロジックを構築する場合でも、YARA-L のコア構造を理解し、その使用方法を実践的に学ぶのに役立ちます。

始める前に

Google SecOps プラットフォームにアクセスできることを確認します。
テストルールを使用してデータの取り込みを検証する。
セキュリティのコンセプトとログデータに関する基本的な知識が必要です。
このドキュメントでは、データが Google SecOps インスタンスに取り込まれ、統合データモデル（UDM）に正規化されていることを前提としています。

YARA-L の構造を理解する

すべての YARA-L クエリは、クエリの動作を決定する、名前付きの個別のセクションに分割されます。

この構造により、多段階の分析と相関関係が可能になります。

コマンド	アクション	省略可 \| 必須
`meta`	作成者、説明、重要度など、ルールの説明的なメタデータを設定します。	検索とダッシュボードでは省略可能です。ルールでのみ必須です。
`events`	イベントを定義してフィルタします。考慮するすべてのデータソース（主にイベント）を宣言し、UDM フィールドを使用してフィルタします。	検索、ダッシュボード、ルールに必須（クエリのコアロジック）。
`match`	イベントでグループ化し、サポートされている時間枠（`by 5m` など）を指定できます。	集計が行われる統計検索では、場合によっては必須です。マルチイベント相関クエリに必要です。ルールの `match` では時間指定が必要ですが、検索とダッシュボードでは省略可能です。
`outcome`	重要な指標を計算し、分析情報を取得します（`count()`、`avg()` など）。	省略可。
`condition`	結果を返す（検索）か、アラートをトリガーする（ルール）ために満たす必要があるロジックを定義します。クエリ変数の条件を評価して、結果が適用されるかどうかを判断します（例: `$event >5`）。	検索とダッシュボードでは省略可能です。ルールでのみ必須です。
`dedup`	キー変数またはイベントパス（`target.user.userid`、`target.ip`、`principal.hostname` など、または `$host`、`$user` などの変数）に基づいてイベントをグループ化し、重複するイベントを削除します。イベント変数の詳細	省略可。ルールでは使用できません。
`order`	特定のフィールド（`asc` など）で定義された結果を並べ替えます。	省略可（`match` が使用されている場合にのみ適用されます）。ルールでは使用できません。
`limit`	クエリから返されるイベントの最大数を制限します。	省略可。ルールでは使用できません。
`select`	クエリ結果に含める UDM フィールドのリストを指定します。	省略可。ルールでは使用できません。
`unselect`	クエリ結果から除外する UDM フィールドのリストを指定します。	省略可。ルールでは使用できません。

YARA-L データソースの可用性

YARA-L は、プラットフォームのどの部分にいるかによって、アクセスできるデータソースが異なります。イベント、エンティティ（ECG）、データテーブルは、検索、ダッシュボード、ルールで完全に利用できます。

次の表に、YARA-L で使用可能な機能を示します。

機能	利用可能
ケースとケース履歴	ダッシュボード
データテーブル	検索、ダッシュボード、ルール
エンティティ（心電図）	検索、ダッシュボード、ルール
Ingestion metrics	ダッシュボード
IoC の一致	ダッシュボード
ルール検出	ダッシュボード、ルール
Rule sets	ダッシュボード
イベント	検索、ダッシュボード、ルール
UEBA 指標	検索、ダッシュボード

初めての YARA-L 検索を作成する

Google SecOps のすべてのデータは、目標に応じて 2 つの主要な方法（フィルタ検索と統計検索（集計））を使用して検索されます。

検索のフィルタ（イベントフィルタリング）

フィルタ検索メソッドを使用すると、統計集計のオーバーヘッドなしで、より広範なテレメトリーストリームから特定のイベントを分離できます。この方法では、基準を使用して、ログやネットワークトラフィックなどの大量のセキュリティデータを絞り込み、ターゲットを絞った結果セットにします。このロジックでは、events セクションでイベントを指定するだけで済みます。

最初の YARA-L フィルタ検索を作成するには、次の手順に沿ってログインに失敗したユーザーを検索します。

Google SecOps で、[検索] ページに移動します。
ログインイベントをフィルタします。
metadata.event_type = "USER_LOGIN"

ヒント: 検索では events: セクションヘッダーを省略できます。デフォルトでは、検索構文はこのセクションを意味します。
userid が空でないユーザーのログイン失敗に対する event アクションを追加します。
```
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
```
この検索を実行して結果を確認します。

プレースホルダ変数を使用する

プレースホルダ変数を使用すると、イベントから特定の値（ユーザー名や IP アドレスなど）を抽出できます。これらの変数は、異なるイベント間でデータを比較したり、最終的な出力でこれらの値を表示したりするための、一時的なアンカーとして機能します。

プレースホルダ変数を適用して、次の操作を行います。

ブリッジデータ: $userid や $ip などのプレースホルダを使用して、異なるイベント変数間の一致を見つけます（たとえば、$userid を使用して、ログインイベントとログアウトイベント間でユーザー ID をリンクできます）。
結果をグループ化する: match セクションで、プレースホルダ変数を使用して、クエリ出力のウィンドウ（match: $userid over 1h など）を定義します。
結果を作成する: プレースホルダを使用して、クエリ出力で特定のデータポイントを取得して表示します。

たとえば、$user = principal.user.userid を割り当てると、$user 変数にはイベントから抽出された特定の値が保持されます。次に、match セクションで $user を使用して、その特定のユーザーに関連するすべてのアクティビティをグループ化します。

統計検索（集計）

統計検索メソッドを使用すると、イベントのセット全体で計算を実行して、分析情報、傾向、異常を取得できます。個々のログのリストを返すのではなく、データの集計された概要を提供します。このロジックでは、match セクション（グループ化用）と outcome セクション（計算用）を使用します。outcome セクションは、count()、sum()、avg()、max()、min()、stddev() などの集計関数をサポートしています。

次の例では、次のクエリロジックを使用しています。

events: ログイン試行の失敗に関する生データをフィルタします。
match: グループ化イベント（userid による）を定義します。
outcome: 統計集計（ユーザーあたりのイベント数）を実行します。

例: `outcome` 関数を使用してログイン失敗アクティビティを集計する

次の例では、outcome セクションの集計関数（count() や sum() など）を使用して、ログイン失敗アクティビティを要約しています。

match セクションを使用して、userid でログイン失敗イベントをグループ化します。

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.user.userid

outcome 変数で定義された、各ユーザー（$failed_login_count）のログイン失敗回数の count を使用します。

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.$user.userid

outcome:
  $failed_login_count = count(metadata.id)

この検索を実行して結果を確認します。

省略可: match セクションに時間の要素（この場合は day）を追加します。次に、outcome 変数をより明示的に（$daily_failed_login_count）更新します。

metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
$user =principal.user.userid

match:
  principal.$user.userid by day

outcome:
  $daily_failed_login_count = count(metadata.id)

最初の検索の作成例で示したように、集計された検索からダッシュボードウィジェットを作成できます。

検索が検証されたら、次の手順でウィジェットとして保存してダッシュボードに追加できます。

結果が表示されたら、[Visualize] タブ > [Add to Dashboard] をクリックします。
ウィジェットを構成します。
1. ウィジェットに名前を付けます（例: "Daily Failed Login"）。
2. 期間を選択します。
3. 既存のダッシュボードに追加するか、新しいダッシュボードに追加するかを選択します。
4. [追加] をクリックします。
省略可: クエリをダッシュボードに直接組み込みます。または、キュレートされたダッシュボードをコピーして、その中のクエリの編集内容を変更することもできます。
省略可: カスタムダッシュボードを作成し、YARA-L を使用してウィジェットを追加できます。詳細については、カスタムダッシュボードを作成するをご覧ください。

ダッシュボードを構成する

新しいダッシュボードを作成する場合、events セクションは必須の出発点です。そこから、match（結果のグループ化用）または outcome（出力と集計の計算用）を柔軟に使用できます。

たとえば、events セクションと match セクションを含むダッシュボードを作成できます。このダッシュボードには、検出の重大度（$severity）が by hour バケットにグループ化されて表示されます。

例: 重大度別に時系列を集計する

events セクションと match セクションを使用して、hour バケットにグループ化された検出の重要度（$severity）を表示するダッシュボードを作成できます。

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

例: 重大な影響の合計を集計する

同様に、events セクションと outcome セクションを使用して、重大度の高い検出を追跡するダッシュボードを作成できます。

detection.detection.severity = "CRITICAL"
$severity = detection.detection.severity

outcome:
  $detection_count = count_distinct($severity)

例: 重大度別の検出数の推移を可視化する

次の例では、重大な検出数をカウントし、コンソールで期間を指定できます。多くの場合、ダッシュボードで可視化を作成するときに、match セクションと outcome セクションの両方を使用します。

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

outcome:
  $detection_count = count_distinct(detection.id)

例: ユーザーログインの頻度を計算する

次の例では、match セクションと outcome セクションを使用して、特定のユーザーの login_count を計算することに焦点を当てています。

events:
  metadata.event_type = "USER_LOGIN"

match:
  target.user.userid

outcome:
  $login_count = count(metadata.id)

ルールを作成する

ルールには次のセクションが必要です。

meta: ルール名と説明の詳細が含まれます。
events: イベント変数を使用してデータソースとフィルタを定義します。
condition: ルールをトリガーするために存在する必要があるイベント変数を指定します。

イベント変数を定義して使用する

イベント変数は論理コンテナとして機能し、フィルタをグループ化して、検索、ルール、ダッシュボード全体でその特定のアクティビティを参照できるようにします。

events セクションでロジックを定義する際に、イベント変数（$e など）を使用して、条件に一致する特定のイベント（またはイベントのグループ）を表すことができます。

例: イベント変数を定義してフィルタする

イベント変数（$e など）を定義するには、クエリの events セクションで接頭辞を使用します。これにより、これらのイベントが変数で表されることが宣言されます。たとえば、式 $e.principal.hostname = "dev" は、各イベントを評価して、ホスト名が完全に一致するかどうかを判断します。

$e.principal.hostname = "dev"
$e.metadata.event_type = "USER_LOGIN"

その後、クエリの他のセクションでその変数を使用して、特定のイベントグループ（match、outcome、condition セクション）とそのデータフィールドを参照できます。

ルールの構造と構文を整理する

次のルール構造と構文を使用して、変数、グループ化ロジック、トリガーしきい値を定義します。

要素	説明	例
ルールの構造	クエリを `rule` ブロックでラップし、検出を識別する一意の名前を割り当てます。	`rule DailyFailedLoginAttempts { }`
`meta` セクション	必須。ルールの管理を改善し、チームにコンテキストを提供するための説明的なメタデータ（`author`、`description`、`severity` など）が含まれます。ルール管理のベストプラクティスとして推奨されます。	`author = "Alex"` `severity = "Medium"`
イベント変数	ルールクエリでは、`events` セクションの各フィールドの前にイベント変数（`$e` など）が付加され、条件に一致する特定のイベント（またはイベントのグループ）を表します。これらはフィルタの論理グループとして機能します。検索を YARA-L ルールに変換するの例では、`$e` はユーザーのログイン失敗をすべて表しています。	`$e.metadata.event_type = "USER_LOGIN"`
プレースホルダ変数	イベントに共通名を割り当てます。この名前は、後でクエリで参照できます。詳しくは、プレースホルダ変数を使用するをご覧ください。	`$userid = $e.principal.user.userid`
`match` セクション	グループを定義し、サポートされている時間枠を指定します。検索を YARA-L ルールに変換するの例では、`match: $userid over day` グループ化により、各 24 時間（`1d`）内のユーザー ID でイベントが正しくグループ化されます。ルールを作成するときは、ルックバック期間を定義するためにサポートされている時間枠を指定する必要があります。ロジックの要件に応じて、ホップウィンドウ、スライディングウィンドウ、タンブリングウィンドウを実装できます。`over` 演算子を明示的に使用すると、ホップウィンドウが作成されます。	`$userid over 1d`
`outcome` セクション	統計的集計を実行するか、特定の変数をキャプチャして、結果のアラートの情報を充実させます。 `$e.metadata.id` で `count()` 関数を使用して、各 `match` グループ内のイベントを集計します。また、`$userid` などの変数を割り当てて、特定の UDM フィールドをキャプチャし、検出結果の出力でより多くのコンテキストを提供することもできます。	`$failed_count = count($e.metadata.id)`
`condition` セクション	ルールで検出を生成するために必要です。 `condition` セクションで検出のしきい値を定義します。たとえば、`#e > 5` を使用するには、アラートをトリガーするためにイベント数が 5（`5`）を超える必要があります。計算を行わない場合でも、`condition` セクションは必要です。イベント変数（`#e` など）の存在を明記してください。環境のベースラインを分析して、不審なアクティビティを検出し、誤検出を最小限に抑えるしきい値を設定します。計算を行わない場合でも、`condition` セクションは必要です。イベント変数の存在を `#e` のように記述します。	`#e > 5` または `$e`

この構造の仕組みについては、次の例をご覧ください。

例: ブルートフォース（ログイン失敗の繰り返し）を検出する

次の例では、24 時間以内に 1 人のユーザーによるログイン試行が複数回失敗した場合を検出します。

rule DailyFailedLoginAttempts {
  meta:
    author = "Alex"
    description = "Detects multiple failed login attempts for a single user within a day."
    severity = "Medium"

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

  match:
    $userid over 1d

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

  condition:
    $daily_failed_login_count > 5
}

検索を YARA-L ルールに変換する

通常、確定した検索クエリを検出を生成するための信頼性の高いルールに変換するには、次の手順を行います。

Google SecOps で、ルールエディタに移動します。
新しいルールを開始します。
検索クエリを貼り付け、ルール構造に合わせて変更します。変更内容には次のものが含まれます。
- meta セクション: ルール名、作成者、重大度レベルなどのメタデータルールを定義します。
- event セクション: 必須。検索とは異なり、名前付きの event セクションヘッダーが必要です。
- イベント変数: ロジック内の特定のイベント（またはイベントのグループ）を宣言して参照します。
- サポートされている時間枠を含む match セクション: グループ化キーを指定し、時間パラメータ（5m や 1d など）を定義します。注: ルールで match セクションを使用する場合は、時間枠を追加する必要があります。
- condition セクション: ルールをトリガーするために満たす必要のある最終的なロジックまたはしきい値を定義します。

上級: マルチイベントルールを作成する

マルチイベントルールを使用して、特定の期間内に発生するさまざまなタイプのアクティビティを関連付けます。単一のイベントを調べるのではなく、ユーザーがログインした直後に異常なファイルをダウンロードしたなどの複数のイベントを関連付けて、複雑な脅威を特定します。

マルチイベントルールには次のセクションが必要です。

meta: ルール名と説明の詳細が含まれます。
events: イベント変数を使用してデータソースとフィルタを定義します。
match: イベントのブリッジに使用される期間とプレースホルダ変数を設定します。
outcomeアラートの追加のコンテキストをキャプチャします。マルチイベントルールには、集計関数が必要です。
condition: ルールをトリガーするために存在する必要があるイベント変数を指定します。

マルチイベントルールを作成する手順は次のとおりです。

イベント変数を定義する: イベントセクションで、"PROCESS_LAUNCH" イベントをキャプチャする $e1 と、特定の悪意のあるファイルのハッシュをキャプチャする $e2 を定義します。
プレースホルダと関連付ける: $user プレースホルダ変数を使用して、共有プリンシパルユーザー ID（$user = $e1.principal.user.userid and $user = $e2.principal.user.userid など）でこれら 2 つの異なるイベントストリームを接続します。
一致をグループ化する: match セクションで、これらのイベントが同じ $user で、5 分（5m）などの設定された時間枠内で発生する必要があることを指定します。

例: マルチイベントルールを作成する

次の例では、$e1 は PROCESS_LAUNCH イベントを表し、$e2 は特定の悪意のあるハッシュを含むイベントを表します。$user プレースホルダ変数は、これらのイベントを同じプリンシパルユーザー ID で関連付けます。

rule MultiEventExample {
  meta:
    author = "Alex"
    description = "Detects a bad hash execution or a process launch from a specific IP for the same user."

  events:
    $e1.principal.ip = "1.1.1.1"
    $e1.metadata.event_type = "PROCESS_LAUNCH"
    $e2.target.file.sha256 = "badhash..."
    $user = $e1.principal.user.userid
    $user = $e2.principal.user.userid

  match:
    $user over 5m

  condition:
    $e1 or $e2
}

次のルールコンポーネントは、この例で使用されるロジックを表しています。

イベント変数: 2 つのイベント変数 $e1 と $e2 を定義しました。プレースホルダ変数 $user を使用して、共通の userid フィールドでこれらのイベントを結合しました。
match セクション: このマルチイベントルールに match セクションを追加して、ユーザーでグループ化し、イベントを関連付ける 5 分間のホップ時間枠（5m）を指定しました。
condition セクション: アラートをトリガーするロジックを定義します。この例では、最初または 2 番目のイベントが存在する場合にアラートがトリガーされます。

他のツールを使用してクエリを作成する

これらのツールは、YARA-L の作成、検証、導入の加速に不可欠なコンパニオンです。

UDM Lookup ツール: UI 内で UDM フィールド名、定義、データ型をすばやく検索して参照できます。フィールド ID が不明な場合は、このリファレンスの確認を優先します。
自然言語から YARA-L への検索: 検索バーに説明を入力して、最初のクエリを作成したり、対応する YARA-L の候補を取得または変換したりします。
SPL → YARA-L 変換ツール（ラボツール）: 競合他社のプラットフォームから移行する場合は、このツール（[ラボ] セクションで使用可能）を使用して、以前の Splunk SPL クエリを YARA-L に変換します。これにより、構造化された出発点が生成され、移行が加速し、検出ロジックが洗練されます。Labs ツールを使用するには、Google SecOps で yourinstancename.chronicle.security/labs に移動します。

次のステップ

YARA-L 2.0 言語の構文の詳細を確認する
YARA-L 2.0 の関数を参照する
その他の例については、Google SecOps コミュニティをご覧ください。

さらにサポートが必要な場合 コミュニティメンバーや Google SecOps のプロフェッショナルから回答を得ることができます。