应用 YARA-L 2.0 窗口化逻辑

支持的环境：

Google SecOps SIEM

本指南可帮助安全工程师为查询选择正确的窗口类型，以避免“变量未绑定”编译器错误。从滑动窗口过渡到翻滚窗口后，您可以构建依赖于事件缺失的逻辑，例如缺少检测信号或日志源失败。

准备工作

确认您的账号具有以下角色之一，以便创建和修改 YARA-L 查询：

• Detection Engine Admin (roles/chronicle.detectionEngineAdmin)
• SecOps Editor (roles/chronicle.editor)

支持的窗口类型

YARA-L 2.0 使用不同的窗口化行为来确定如何对时间进行切片以及如何将事件分组。您可以使用以下支持的窗口，按指定的 时间粒度在 match 部分中对事件字段和占位符进行分组：

支持的窗口类型	语法	说明	常见用例
跃点	$key over <duration>	创建固定的重叠时间间隔。系统会定义重叠和对齐方式，以捕获边界附近的事件。	多个事件的一般关联，无论确切的开始时间如何。
翻滚	$key by <duration>	将数据分段为固定大小的连续非重叠块。独立于事件到达进行评估。	量化固定时段内的活动（例如 $user by 30m）或检测事件缺失。
滑动	$key over <duration> [before|after] $pivot	将窗口锚定到特定的 "pivot" 事件。需要存在数据透视表才能触发回溯或前瞻。	事件顺序至关重要的严格排序（例如 File Download after Login）。

了解 window_start 和 window_end 逻辑

Google Security Operations 提供了两个通用预留关键字，它们直接解析为 GoogleSQL 时间戳，以便在查询中使用。借助这些关键字，您可以访问时间分桶的边界：

• window_start：时间分桶的起始边界。
• window_end：时间分桶的结束边界。

使用限制

• 匹配要求： 您必须在 match 部分中定义窗口（by 或 over），才能使用这些关键字。
• 部分限制： 在 condition、order 或 outcome 中使用这些关键字。它们在 events 部分中无效。
• 命名空间： 请勿将这些关键字用作自定义变量名称（例如 $window_start）。

确定窗口类型和语法

在确定检测规则要使用的窗口类型和语法时，请使用此表作为快速参考。

场景	推荐的窗口	推荐的关键字	主要优点
高频检测 （例如暴力破解攻击）	滑动窗口 (over)	window_start、window_end	在滚动时间段内达到阈值时立即触发。
缺失/不存在 （例如缺少检测信号）	翻滚窗口 (by)	window_start、window_end	即使发生零个事件，也会评估固定时间块，从而避免 变量未绑定错误。
按时间顺序报告	滑动或翻滚	order: window_start asc	标准化提醒输出，以便在 Chronicle 界面中更轻松地进行时间轴分析。
时间限定过滤	滑动或翻滚	condition: window_start > "2026-01-01 00:00:00Z"	使用 GoogleSQL 时间戳强制转换将规则评估限制为特定日期。

比较时间戳类型和时区

YARA-L 支持直接将 window_start 和 window_end 与 GoogleSQL 时间戳格式的字符串进行比较。这样，您无需手动进行类型转换即可执行精确过滤。

注意： 请始终使用 Z 后缀（例如 "2026-03-17T17:35:00Z"）指定 UTC，以便与 UDM 事件时间戳保持一致。

使用时间戳过滤条件可提高性能。如果您只需要确认一个事件发生在另一个事件之后，则 condition 部分中的时间戳比较通常更高效：$e1.metadata.event_timestamp.seconds < $e2.metadata.event_timestamp.seconds。

详细了解 match 部分语法 和 condition 部分语法。

示例：window_end 和 window_start

• window_end < "2026-01-01T12:30:00Z"（日期、时间和 UTC 后缀）
• window_start != "2026-01-01 15:00:00+00"（带 UTC 偏移量）

如果比较失败，请验证您的字符串是否遵循 GoogleSQL 规范时间戳格式。

跃点窗口

跃点窗口会创建重叠的时间间隔，因此不会错过窗口边界附近发生的事件。

• 用例： 最适合需要捕获特定场景的检测，无论窗口间隔的确切开始或结束时间如何。
• 支持： 支持在搜索和信息中心内进行聚合。

包含 match 部分的 YARA-L 查询使用跃点窗口来关联多个事件随时间的变化。系统会将查询执行的时间范围划分为一组固定的重叠跃点窗口。虽然您可以在 match 部分中指定这些窗口的时长，但系统会定义重叠间隔和窗口对齐方式。然后，事件会在每个预先确定的窗口内关联。

注意： 除非您需要特定的事件序列（先是订单 A，然后是订单 B），否则请使用跃点窗口。仅当事件排序至关重要或您搜索缺失事件时，才使用滑动窗口。

详细了解 match 部分语法。

跃点窗口对复合规则检测有特定的影响。如需了解详情，请参阅复合规则：时间间隔和跃点窗口。

示例：用于持续关联的重叠跃点窗口

以下示例展示了在时间范围 [1:00, 2:00] 内运行的查询，其中包含 match 部分 $user over 30m。系统生成的一组可能的重叠跃点窗口为 [1:00, 1:30]、[1:03, 1:33] 和 [1:06, 1:36]。

规则

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

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

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

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

搜索

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

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

信息中心

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

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

示例：使用跃点窗口进行多事件关联

以下示例捕获在同一大致时间范围内发生的事件：

规则

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

events:
  // Event 1: Capture failed login attempts
  $fail.metadata.event_type = "USER_LOGIN"
  $fail.security_result.action = "FAIL"
  $fail.principal.user.userid = $user

  // Event 2: Capture successful login attempts
  $success.metadata.event_type = "USER_LOGIN"
  $success.security_result.action = "ALLOW"
  $success.principal.user.userid = $user

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

condition:
  // Ensure both a failed ($fail) and a successful ($success) login event occurred for the same user within the 30m window.
  $fail and $success
}

搜索

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

信息中心

// Event 1: Capture failed login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid = $user // Assign user ID to a placeholder

// Event 2: Capture successful login attempts
metadata.event_type = "USER_LOGIN"
security_result.action = "ALLOW"
principal.user.userid = $user // Link to the same user placeholder

match:
  // Correlate events for the SAME $user within a rolling 30-minute window.
  $user over 30m

示例：跃点窗口比较

如需识别暴力破解尝试，10m 窗口会将所有 USER_LOGIN 失败分组。然后，条件会评估该特定 10 分钟分桶内的计数 (#e) 是否超过您的阈值。

规则

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

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

match:
  $user over 10m

condition:
  #e >= 5
}

搜索

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

match:
  $user over 10m

信息中心

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

match:
  $user over 10m

翻滚窗口

注意： 此功能受 Google Security Operations 服务专用条款的正式发布前产品条款的约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则 和 Google SecOps 服务专用条款。
如果您的环境中未显示此功能，请参阅管理预览版功能或与系统管理员联系。

注意：此功能并非适用于所有区域的所有客户。

翻滚窗口会将数据分段为固定大小的非重叠连续时间间隔。每个事件的时间戳都恰好属于一个窗口。翻滚窗口之间没有重叠。这与跃点窗口或滑动窗口形成对比，后者可以具有重叠的时间间隔。

如需实现翻滚窗口，请在 match 部分中使用 by 运算符。翻滚窗口会将时间划分为连续的背靠背块，例如：

• by 1h：为每个小时创建窗口（例如 [00:00:00-00:59:59]、[01:00:00-01:59:59]）。
• by 10m：为每个 10 分钟间隔创建窗口（例如 [00:00:00-00:09:59]、[00:10:00-00:19:59]）。

常见用例

在需要执行以下操作时，请使用翻滚窗口：

• 分析不同的非重叠时间块中的事件。
• 在每个固定时间间隔内，针对给定实体（由匹配变量定义）仅生成一个检测，无论事件发生多少次。
• 统计固定时间段内的唯一实体。

重复信息删除行为

翻滚窗口的一个关键特征是，引擎如何处理每个窗口内针对同一组匹配变量的检测：

• 每个窗口一个检测： 对于给定的一组匹配变量值（例如特定的 $userid），引擎最多为任何单个翻滚窗口生成一个检测。
• 先到者胜出： 在特定窗口内，第一个满足该组匹配变量的规则条件的事件会触发检测。
• 重复信息删除： 在同一窗口实例中，任何后续事件如果符合条件，都不会生成额外的检测。

语法

match 部分中的语法为：match: $variable by <duration>

• $variable 是您要匹配的占位符变量。
• duration 是一个数字，后跟一个时间单位：m（分钟）、h（小时）、d（天）。
• 指定至少一分钟，最多 72 小时或三天。

示例：固定间隔分组

以下规则按 $userid 在 1 小时的非重叠窗口内对登录进行分组。

规则

rule TumblingWindowExample {
meta:
  description = "Example using a 1-hour tumbling window"

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

match:
  $userid by 1h

condition:
  $e
}

搜索

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

信息中心

metadata.event_type = "USER_LOGIN"
principal.user.userid = $userid

match:
  $userid by 1h

示例：检测行为（用户 =“Alex”）

• 事件 1： Alex 在 00:30 登录。这属于 [00:00:00-00:59:59] 窗口。引擎会为此窗口生成针对 Alex 的检测。
• 事件 2： 另一位用户“Taylor”在 00:45 登录。这也属于 [00:00:00-00:59:59]，但由于 $userid 不同，引擎会为 Taylor 生成单独的检测。
• 事件 3： Alex 在 00:40 再次登录。这仍在 [00:00:00-00:59:59] 窗口内。由于针对 Alex 的检测已存在，因此系统会删除此事件的重复信息。不会生成新的检测。
• 事件 4： Alex 在 01:20 登录。这属于下一个窗口 [01:00:00-01:59:59]。引擎会为 Alex 生成新的检测。

尽管 Alex 的事件 1 和事件 4 发生时间相隔不到一小时，但它们属于单独的检测，因为事件 4 跨越了固定窗口边界。

为缺失检测配置翻滚窗口

如需在计数为零时发出提醒并避免编译器失败，请完成以下步骤：

1. 确定检测目标。确定您要搜索的是高频活动还是缺少活动。
2. 选择 window关键字。对于频率，使用 over；对于缺失，使用 by。
3. 引用窗口边界。使用 window_start 和 window_end 关键字引用时间分桶的特定边界。

上下文： 使用 outcome: $ext_window_end = window_end 在提醒元数据中包含缺失检测信号的确切结束时间。

示例：检测缺失的检测信号（带元数据）

翻滚窗口可让您在计数为零时发出提醒，这有助于您在搜索缺少活动时避免编译器失败。

规则

rule missing_heartbeat_detection {
meta:
  description = "Alert when a system fails to check in within a 24h block"

events:
  $e.metadata.event_type = "STATUS_UPDATE"
  $host = $e.principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count($e.metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

condition:
  $event_count = 0 and window_start > "2026-01-01T12:30:00Z"
}

搜索

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

信息中心

metadata.event_type = "STATUS_UPDATE"
$host = principal.hostname

match:
  $host by 24h  // Tumbling window lets you detect zero counts

outcome:
  $event_count = count(metadata.id)
  $missing_window_start = window_start
  $missing_window_end = window_end

滑动窗口

滑动窗口锚定到特定的数据透视事件，并向前 (after) 或向后 (before) 查看。

**注意：** 仅适用于规则；搜索或信息中心不支持此功能。

常见用例

当事件排序至关重要时，请使用滑动窗口：

• 严格排序： 检测攻击链（例如，e1 最多在 e2 之后两分钟发生）。
• 相对时间： 查找在触发器特定偏移量内发生的事件（例如，Process Start 后 30 秒内的 Network Connection）。
• 缺失检测： 确定在开始事件后，所需的“清理”或“检测信号”事件何时未能发生。

语法

match: <grouping_keys> over <duration> [before|after] <$pivot_event>

组件	说明	示例
分组键	用于将事件链接在一起的常用字段。	$host、$user
时长	相对于数据透视事件的时间偏移值。	5m、1h、30s
方向	窗口是向前还是向后延伸。	after、before
转换事件	锚定窗口的事件变量。	$proc、$alert

以下是有效的滑动窗口示例：

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

要求和限制

• 性能：滑动窗口比跃点窗口需要更多的处理能力。仅当严格要求事件顺序时才使用它们（例如，一个事件必须在另一个事件发生后五分钟内发生）。
• 单事件查询：请勿将滑动窗口用于单事件逻辑。请改用 condition 部分中的多个事件变量。

示例：前瞻性关联 (after)

规则

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

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

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

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

condition:
  $proc and $net
}

搜索

搜索不支持 after。

信息中心

信息中心不支持 after。

示例：回溯性关联 (before)

使用 "before" 滑动窗口调查导致特定提醒的活动。这通常用于根本原因分析，以确定在关键检测之前立即发生了什么。

规则

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

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

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

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

condition:
  $file and $alert
}

搜索

搜索不支持 before。

信息中心

信息中心不支持 before。

问题排查

使用本部分了解 YARA-L 中常见窗口化问题的延迟时间、限制和修复方法。

延迟时间和限制

• 使用翻滚窗口 (by) 的规则仅在固定时间块结束时触发。例如，包含 match: $user by 24h 的规则仅在 24 小时窗口完全结束后进行评估。

• 提醒延迟时间： 使用 by（翻滚）的规则仅在固定时间块结束后触发。by 24h 规则不会在窗口中间发出提醒。

• 界面不匹配： 在搜索和信息中心内，window_start 关键字直接引用 TIME_BUCKET 字段。当您按 window_start 进行过滤或分组时，列标题在界面中显示为 TIME_BUCKET。这是一个已知的界面显示限制；您的逻辑仍然有效。

错误修复

错误代码	说明	修复
变量未绑定	规则使用 over（滑动窗口）和 $count = 0 条件。	将窗口化关键字更改为 by（翻滚窗口）。滑动窗口需要存在事件才能锚定窗口，而翻滚窗口则不需要。
界面标题不匹配	用户在界面中看到的是 TIME_BUCKET，而不是 window_start。	无需修复。过滤和排序逻辑仍可使用关键字正常运行。
未知标识符： window_start	使用了关键字，但在 match 中未定义窗口。	向 match 部分添加窗口化语句（例如 $hostname by 1h）。
在事件中无效使用 window_start	关键字在 events 部分中被引用。	将逻辑移至 condition 或 outcome 部分。窗口边界仅在事件在匹配阶段分组后计算。

后续步骤

• YARA-L 2.0 查询参考库
• match 部分语法
• condition 部分语法

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。