リスク分析ルールの指標関数

このドキュメントでは、リスク分析の新しい YARA-L 構文機能の主な要素について説明します。YARA-L の詳細については、YARA-L 2.0 言語の構文をご覧ください。

YARA-L 指標関数

Google Security Operations は、大量の履歴データを集計できるさまざまな指標関数をサポートしています。

指標関数は結果セクションでのみ使用できます。すべての関数呼び出しの例は、マルチイベント ルールでの使用を前提としています。

指標関数を使用するすべてのルールは、一致セクションがなく、1 つのイベント変数のみを使用する場合でも、自動的にマルチイベント ルールとして分類されます。つまり、マルチイベント ルールの割り当ての対象になります。

指標関数のパラメータ

指標関数は、エンティティの行動分析を実行するルールに使用できます。

たとえば、次のルールは、特定の IP アドレスが過去 1 か月間に送信した 1 日あたりの最大バイト数を示します。特定の IP アドレスは、プレースホルダ変数（この例では $ip）で表されます。プレースホルダ変数の詳細については、変数宣言をご覧ください。

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
))

これらの関数で使用される引数の数が多いため、名前付きパラメータを使用します。名前付きパラメータは任意の順序で指定できます。パラメータは以下のとおりです。

期間

個々のログイベントが単一の観測情報に統合される期間。使用できる値は 1h と 1d のみです。

ウィンドウ

個々の観測情報が単一の値（平均値や最大値など）に集計される期間。window に指定できる値は、指標の期間に基づきます。有効なマッピングは次のとおりです。

period:1h: window:today

period:1d: window:30d

たとえば、次のルールは、過去 30 日間に特定のユーザー（Alice）に対して 1 日に発生した認証失敗の最大回数を返します。

$user = "alice"
$max_fail = max(metrics.auth_attempts_fail(
    period:1d, window:30d,
        metric:event_count_sum,
        agg:max,
        target.user.userid:$user
))

first-seen タイプの検出には、1 時間単位の指標と 1 日単位の指標の組み合わせを使用できます。たとえば、次のルールは、ユーザーがこのアプリケーションに初めてログインしたかどうかを示します。

events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "ALLOW"
    $userid = $e.target.user.userid
    $app = $e.target.application
match:
    // find events from now - 4h ago, which is the recommended look-back period
    $userid, $app over 4h
outcome:
    // check hourly analytics until daily analytics are available
    $first_seen_today = max(metrics.auth_attempts_success(
        period:1h, window:today, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
    $first_seen_monthly = max(metrics.auth_attempts_success(
        period:1d, window:30d, metric:first_seen, agg:max,
        target.user.userid:$userid, target.application:$app))
condition:
    $e and ($first_seen_today = 0) and ($first_seen_monthly = 0)

指標

各期間内で、各観測情報に複数の指標が関連付けられます。 ウィンドウ全体の集計には、これらのいずれかを選択する必要があります。次の 5 つの metric タイプがサポートされています。

event_count_sum - 各期間内の一意のログイベントの数。

first_seen - 各期間内で一致するログイベントの最初のタイムスタンプ。

last_seen - 各期間内で一致するログイベントの最終のタイムスタンプ。

value_sum - 期間内のすべてのログイベントのバイト数の合計を表します。この値は、名前に bytes が含まれる指標関数でのみ使用できます。

num_unique_filter_values - Google SecOps によって事前計算されないが、ルールの実行中に計算できる指標。詳細と要件については、一意の指標をカウントするをご覧ください。

Agg

指標に適用される集計。集計はウィンドウ全体で適用されます（例: 過去 30 日間の 1 日あたりの最大値）。使用できる値は次のとおりです。

avg - 期間あたりの平均値。これは統計的な平均値であり、ゼロの値は含まれません。

max - 期間あたりの最大値。

min - 期間ごとの最小値。

num_metric_periods - 指標値がゼロ以外の値だった期間の数。

stddev - 期間あたりの値の標準偏差。これは、ゼロ値を含まない統計標準偏差です。

sum - ウィンドウ全体で、期間ごとの各値の合計。

たとえば、次のルールは、過去 30 日間の特定の日において、特定のユーザー（Alice）で発生した認証失敗の平均回数を返します。

$user = "alice"
$avg_fail = max(metrics.auth_attempts_fail(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:avg,
        target.user.userid:$user
))

次のルールは、特定のユーザーが過去 30 日間に正常に認証された回数を示します。

$total_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:sum,
        target.user.userid:$user
))

次のルールは、特定のユーザーが過去 30 日間に 1 回以上正常にログインしたかどうかを示します。

$days_success = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:event_count_sum,
        agg:num_metric_periods,
        target.user.userid:$user
))

次のルールは、特定のユーザーが初めてまたは最後に正常にログインした日時を示します。

$first_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:first_seen,
        agg:min,
        target.user.userid:$user
))
$last_seen = max(metrics.auth_attempts_success(
        period:1d, window:30d,
        metric:last_seen,
        agg:max,
        target.user.userid:$user
))

次のルールは、過去 30 日間にユーザーが 1 日に送信した最大バイト数を示します。

$max_daily_bytes = max(metrics.network_bytes_outbound(
        period:1d, window:30d,
        metric:value_sum,
        agg:max,
        target.user.userid:$user
))

フィルタ

フィルタを使用すると、事前に計算された指標の値によって、集計前の指標をフィルタリングできます（指標の値をご覧ください）。フィルタには、イベント フィールドやプレースホルダを含まない有効なイベント式（イベント セクションの 1 行）を使用できます。この条件に含めることができる変数は、指標タイプのみです。

次のルールには、value_sum > 10 AND event_count_sum > 2 の指標のみが含まれます。

$max_bytes_per_day = max(metrics.network_bytes_outbound(
    period:1d, window:30d,
    metric:value_sum,
    agg:max,
    principal.asset.ip:$ip
    filter:value_sum > 10 AND event_count_sum > 2
))

フィルタの有効な例

filter:value_sum > 10 AND event_count_sum != 5
filter:event_count_sum = 100 OR event_count_sum > 1000
filter:timestamp.get_day_of_week(first_seen) = 3

無効なフィルタの例

// No placeholders in filter expressions.
filter:value_sum > $ph

// No event fields in filter expressions.
filter:event_count_sum + $e.field > 10

// No event fields in filter expressions.
filter:timestamp.subtract(first_seen, $e.metadata.timestamp)

UDM フィールド

関数に応じて 1 ～ 3 個の UDM フィールドによって指標がフィルタリングされます。 詳細については、関数をご覧ください。

指標関数には、次のタイプの UDM フィールドが使用されます。

• ディメンション -（必須）さまざまな組み合わせがこのドキュメントに記載されています。デフォルト値（文字列の場合は ""、整数の場合は 0）を持つ指標を結合することはできません。
• 名前空間 -（省略可）名前空間は、ディメンションで指定したエンティティにのみ使用できます。たとえば、principal.asset.hostname filter を使用する場合は、principal.namespace filter も使用できます。名前空間フィルタを指定しない場合、すべての名前空間のデータが集約されます。デフォルト値を名前空間フィルタとして使用できます。

時間枠の計算

Google Security Operations は、1 日単位または 1 時間単位の指標ウィンドウを使用して指標を計算します。

1 日ごとの時間枠

30d などのすべての 1 日単位のウィンドウは、同じ方法で決まります。 Google Security Operations は、ルール時間範囲と重複しない最新の利用可能な指標データを使用します。1 日単位の指標の計算には最大 6 時間かかることがあります。また、計算は UTC の日付の終了時刻まで開始されません。前日の指標データは、毎日午前 6 時（UTC）までに利用可能になります。

たとえば、2023 年 10 月 31 日 4:00 UTC から 2023 年 10 月 31 日 7:00 UTC までのイベントデータに対して実行されているルールの場合、2023 年 10 月 31 日の日次指標が生成されたため、指標計算では 2023 年 10 月 1 日から 2023 年 10 月 30 日までのデータが使用されます。2023 年 10 月 31 日 1 時 UTC から 2023 年 10 月 31 日 3 時 UTC までのイベントデータに対して実行されているルールの場合、2023 年 10 月 30 日の日次指標が生成されないため、指標の計算には 2023 年 9 月 30 日から 2023 年 10 月 29 日までのデータが使用されます。

1 時間単位の today 時間枠

1 時間単位の指標のウィンドウは、1 日単位の指標のウィンドウとは異なる方法で計算されます。today の 1 時間単位の指標ウィンドウは、1 日単位の指標の 30d ウィンドウのような静的なサイズではありません。1 時間単位の指標ウィンドウ today には、1 日単位のウィンドウの終了からルール時間ウィンドウの開始までの期間にできるだけ多くのデータが入力されます。

たとえば、2023-10-31 4:00:00 UTC から 2023-10-31 7:00:00 UTC までのイベントデータに対して実行されるルールの場合、毎日の指標の計算では data{101 }2023 年 10 月 1 日～ 2023 年 10 月 30 日（両端を含む）と時間単位の指標ウィンドウの場合、2023 年 10 月 31 日 00:00:00 UTC から 2023 年 10 月 31 日 4:00:00 UTC　までのデータが使用されます。

ユニーク指標のカウント

Google SecOps によって事前計算されず、ルールの実行中に計算される特別なタイプの指標 num_unique_filter_values があります。これは、事前に計算された指標の既存のディメンションを集計することで行われます。たとえば、daily total count of distinct countries that a user attempted to authenticate の指標は、target.user.userid ディメンションと principal.ip_geo_artifact.location.country_or_region ディメンションで事前に計算された auth_attempts_total 指標から、後者のディメンションで一意のカウント集計を実行することで導出できます。

次のルールの例では、一意の指標をカウントします。

$outcome_variable = max(metrics.auth_attempts_total(
    period: 1d,
    window: 30d,
    // This metric type indicates any filter with a wildcard value should be
    // aggregated over each day to produce a new metric on-the-fly.
    metric: num_unique_filter_values,
    agg: max,
    target.user.userid: $userid,
    // Filter whose value should be counted over each day to produce the
    // num_unique_filter_values metric.
    principal.ip_geo_artifact.location.country_or_region: *
))

この機能には次の制限があります。

• 一意の指標を計算する場合、集計できるのは 1 つのフィルタ ディメンションのみです。これは、フィルタ値としてワイルドカード トークン * を使用することで示されます。

関数

このセクションでは、Google Security Operations でサポートされている特定の指標関数に関するドキュメントについて説明します。

アラート イベント

metrics.alert_event_name_count は、Carbon Black、CrowdStrike Falcon、Microsoft Graph API Alerts、Microsoft Sentinel によってアラートが生成された UDM イベントの履歴値を事前計算します。

認証試行

metrics.auth_attempts_total は、USER_LOGIN event type の UDM イベントの履歴値を事前計算します。

metrics.auth_attempts_success ではさらに、イベントに ALLOW の SecurityResult.Action が少なくとも 1 つ必要です。

metrics.auth_attempts_fail では、SecurityResult.Actions のいずれも ALLOW でないことが必要です。

送信 DNS バイト数

metrics.dns_bytes_outbound は、network.sent_bytes が 0 より大きい場合、およびターゲット ポートが 53/udp、53/tcp、または 3000/tcp である UDM イベントの履歴値を事前計算します。 network.sent_bytes は value_sum として使用できます。

DNS クエリ

metrics.dns_queries_total は、network.dns.id に値がある UDM イベントの履歴値を事前計算します。

metrics.dns_queries_success ではさらに、network が必要です。dns.response_code が 0（NoError）であった。

metrics.dns_queries_fail では、network を持つイベントのみが考慮されます。dns.response_code が 0 より大きい。

ファイル実行

metrics.file_executions_total は、PROCESS_LAUNCH event type の UDM イベントの履歴値を事前計算します。

metrics.file_executions_success ではさらに、イベントに ALLOW の SecurityResult.Action が少なくとも 1 つ必要です。

metrics.file_executions_fail では、SecurityResult.Actions のいずれも ALLOW でないことが必要です。

HTTP クエリ

metrics.http_queries_total は、network.http.method に値がある UDM イベントの履歴値を事前計算します。

metrics.http_queries_success ではさらに、network が必要です。http.response_code が 400 より小さい。

metrics.http_queries_fail では、network を持つイベントのみが考慮されます。http.response_code が 400 以上である。

ネットワーク バイト

metrics.network_bytes_inbound は、network.received_bytes にゼロ以外の値がある UDM イベントの履歴値を事前計算し、このフィールドを value_sum として使用できるようにします。

metrics.network_bytes_outbound では、network.sent_bytes にゼロ以外の値が必要で、このフィールドを value_sum として使用できるようにします。

metrics.network_bytes_total は、network.received_bytes または network.sent_bytes（または両方）にゼロ以外の値があるイベントを考慮し、これらの 2 つのフィールドの合計を value_sum として使用できるようにします。

リソースの作成

metrics.resource_creation_total は、RESOURCE_CREATION event type または USER_RESOURCE_CREATION event type の UDM イベントの履歴値を事前計算します。

同等のイベントタイプのリストについては、メタデータ イベントタイプをご覧ください。

metrics.resource_creation_success ではさらに、イベントに ALLOW の SecurityResult.Action が少なくとも 1 つ必要です。

リソースの削除

metrics.resource_deletion_success は、RESOURCE_DELETION event type の UDM イベントの履歴値を事前計算します。さらに、イベントに ALLOW の SecurityResult.Actions が少なくとも 1 つ必要です。

リソースの読み取り

metrics.resource_read_success は、RESOURCE_READ event type の UDM イベントの履歴値を事前計算します。さらに、イベントに ALLOW の SecurityResult.Action が少なくとも 1 つ必要です。

metrics.resource_read_fail では、SecurityResult.Actions のいずれも ALLOW でないことが必要です。

制限事項

指標を使用して YARA-L ルールを作成する場合は、次の制限事項に注意してください。

• デフォルト値（文字列の場合は ""、整数の場合は 0）を持つ指標を結合することはできません。
• をデフォルト値
  • イベントに対応する指標データがない場合、指標関数から返される値は 0 です。
  • 検出に指標データのないイベントがある場合、min を使用して関数を集計すると、0 が返されることがあります。
  • イベントのデータがあるかどうかを確認するには、同じイベントで同じフィルタを使用して num_metric_periods 集計指標を使用します。
• 指標関数は結果セクションでのみ使用できます。
• 指標関数は結果セクションでのみ使用されるため、一致セクションを含むルールの他の値と同様に集計する必要があります。

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