入门：SecOps 中的 YARA-L 2.0

支持的平台：

YARA-L 2.0 是一种独特的、高度结构化的查询语言，可为 Google Security Operations 的所有搜索、信息中心和基于规则的威胁检测提供支持。本文档可帮助您了解 YARA-L 的核心结构，并提供使用该语言的实用步骤，无论您是搜寻威胁的安全分析师，还是构建稳健新逻辑的检测工程师，都可以参考本文档。

本文档介绍了 YARA-L 及其语法，展示了如何使用它来表达从基本过滤条件查询到查找复杂模式的规则的所有内容。您可以使用 YARA-L 查询中的各个部分来支持聚合函数、条件逻辑，并通过联接、模式匹配等方式添加上下文。

准备工作

  • 验证您是否有权访问 Google SecOps 平台。
  • 使用测试规则验证数据注入。
  • 您必须对安全概念和日志数据有基本的了解。
  • 本文档假定数据已提取到您的 Google SecOps 实例中，并已规范化为统一数据模型 (UDM)。
  • 如需快速开始查询迁移，请参阅从 SPL 过渡到 YARA-L 2.0 指南，该指南会将常见的 SPL 命令（例如 stats、eval 和 lookup）转换为 YARA-L outcomes 和 match 条件。

了解 YARA-L 结构

每个 YARA-L 查询都分为不同的命名 部分，这些部分决定了查询的行为。

这种结构支持多阶段分析和关联。

订单 部分 规则 搜索/信息中心 说明
1 meta 必需 可选 为规则设置描述性元数据，例如作者、说明和严重级别。例如，作者 (security team)、说明 (Detects multiple failed user logins within 10-minute windows) 和严重级别 (High)。请参阅 meta 部分语法。
2 events 必需 必需 定义和过滤必须跟踪的事件：用户登录、用户登录失败（事件变量）以及指向用户匹配变量（占位符变量）的链接。声明要考虑的所有数据源（主要是事件），并使用 UDM 字段对其进行过滤。请参阅 events 部分语法。
3 match 必需 可选 按事件分组，并允许您指定支持的时间窗口（例如 by 5m）。在某些情况下，对于统计搜索，此部分是必需的。对于多事件关联查询，此部分是必需的。对于规则，match 中必须指定时间；对于搜索和信息中心，则可选择指定时间。请参阅 match 部分语法。

注意：如果您排除 match 部分，规则就可以与单个事件进行匹配。
4 outcome 可选 可选 计算基本指标并获取数据洞见（例如 count()、avg()）。请参阅 outcome 部分语法。
5 condition 必需 可选 定义必须满足的逻辑，以便返回结果（在搜索中）或触发提醒（在规则中）。评估查询变量条件以确定结果是否适用（例如 $event >5）。请参阅 condition 部分语法。
6 options 可选 可选 允许启用或停用特定规则行为。请参阅 options 部分语法。
7 dedup 不适用 可选 通过根据键变量或事件路径（例如 target.user.userid、target.ip、principal.hostname 或变量，例如 $host、$user）对重复事件进行分组，来移除重复事件。详细了解 事件变量 以及如何 在搜索和信息中心中使用重复数据删除功能。
8 order 不适用 可选 对由特定字段定义的结果进行排序（例如 asc）。详细了解 事件变量。可选（仅在使用了 match 时适用）。
9 limit 不适用 可选 限制查询返回的事件数量上限。
10 select 不适用 可选 指定要包含在查询结果中的 UDM 字段列表。
11 unselect 不适用 可选 指定要从查询结果中排除的 UDM 字段列表。

YARA-L 数据源可用性

YARA-L 可以访问不同的数据源，具体取决于您在平台中的位置。事件、实体 (ECG) 和数据表在搜索、信息中心和规则中完全可用。如需详细了解示例查询，请参阅支持的数据源。

下表列出了 YARA-L 中可用的功能：

功能 支持的平台
支持请求和支持请求历史记录 信息中心
数据表 搜索、信息中心、规则
实体 (ECG) 搜索、信息中心、规则
提取指标 信息中心
IoC 匹配项 信息中心
规则检测 信息中心、规则
规则集 信息中心
事件 搜索、信息中心、规则
UEBA 指标 搜索、信息中心

Google SecOps 中的所有数据都使用两种主要方法进行搜索，具体取决于您的目标：过滤条件搜索和统计搜索（聚合）。

借助 过滤条件搜索 方法，您可以从更广泛的遥测流中隔离特定事件，而无需进行 统计聚合。此方法使用条件将大量安全数据（例如日志或网络流量）缩小到目标结果集。该逻辑仅要求您在 events 部分中指定事件。

如需构建您的第一个 YARA-L 过滤条件搜索，请按照以下步骤搜索登录失败的用户：

  1. 在 Google SecOps 中，前往搜索 页面。
  2. 过滤登录事件：
    metadata.event_type = "USER_LOGIN"

    提示：您可以在搜索中省略 events: 部分标题。默认情况下，搜索语法会暗示此部分。

  3. 为 userid 不为空的用户添加登录失败的 event 操作。 
    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
  4. 运行此搜索以查看结果。

使用占位符变量

使用 占位符变量 从事件中提取特定值，例如用户名或 IP 地址。这些变量充当临时锚点，可让您比较不同事件中的数据，或在最终输出中显示这些值。

您可以使用占位符变量执行以下操作：

  • 桥接数据：使用占位符（例如 $userid 或 $ip）查找不同事件变量之间的匹配项（例如，您可以使用 $userid 关联登录和退出事件中的用户标识符）。
  • 对结果进行分组：在 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()）来汇总登录失败活动。

  1. 使用 match 部分按 userid 对登录失败事件进行分组：

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

match:
  principal.user.userid

  2. 使用由 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)

  3. 运行此搜索以查看结果。

  4. 可选：向 match 部分添加时间元素（在本例中为 day）。然后，更新 outcome 变量以使其更明确 ($daily_failed_login_count)：

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

match:
  $user by day

outcome:
  $daily_failed_login_count = count(metadata.id)

根据搜索结果创建信息中心微件

您可以根据聚合搜索结果创建信息中心微件，如构建第一个搜索示例中所示。

验证搜索后，您可以将其保存为微件并将其添加到信息中心，如下所示：

  1. 看到结果后，点击直观呈现 标签页 > 添加到信息中心。
  2. 配置微件：
    1. 为微件命名（例如 "Daily Failed Login"）。
    2. 选择时间范围。
    3. 选择是将其添加到现有信息中心还是新信息中心。
    4. 点击 Add （添加）。
  3. 可选：直接在信息中心内构建查询。或者，您可以复制精选信息中心，并修改其中的查询，作为起点。
  4. 可选：您可以创建自定义信息中心，并使用 YARA-L 向其中添加微件。如需了解详情，请参阅创建自定义信息中心。

配置信息中心

构建新信息中心时，events 部分是必需的起点。从这里开始，您可以灵活地使用 match（用于对结果进行分组）或 outcome（用于计算输出和聚合）。

例如，您可以拥有一个包含 events 和 match 部分的信息中心，其中信息中心会显示按 by hour 存储分区分组的检测的严重级别 ($severity)。

示例：按严重级别聚合时间序列

  • 您可以使用 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) 才能触发提醒。如果您不执行计算，仍需要 condition 部分并说明事件变量的存在（例如 #e）。

分析环境的基准，以设置捕获可疑活动并最大限度减少误报的阈值。如果您不执行计算，仍需要 condition 部分并说明事件变量的存在，例如 #e。		 #e > 5 或 $e

如需了解此结构的工作原理，请参阅以下示例。

示例：检测暴力破解（多次登录失败）

  • 以下示例检测单个用户在 24 小时窗口内多次登录失败的尝试：

    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
}

如需将最终搜索查询转换为可靠的规则以生成检测，您通常需要执行以下步骤：

  1. 在 Google SecOps 中，前往 规则编辑器。
  2. 启动新规则。
  3. 粘贴搜索查询并对其进行修改，以适应规则结构，包括：
    • meta 部分：定义元数据规则，包括规则名称、作者和严重级别
    • event 部分：必需。与搜索不同，您必须具有命名的 event` 部分标题。
    • 事件变量：在逻辑中声明和引用特定事件（或一组事件）。
    • match 部分（包含 支持的时间窗口）：指定分组键并定义时间参数（例如 5m 或 1d）。注意：如果您在规则中使用 match 部分，则必须添加时间窗口。
    • condition 部分：定义必须满足的最终逻辑或阈值，以触发规则。

高级：构建多事件规则

您可以使用 多事件规则 来关联在特定时间范围内发生的各种类型的活动。您无需查看单个事件，而是关联多个事件（例如用户登录，然后立即执行异常文件下载），以识别复杂威胁。

多事件规则需要以下部分：

  • meta：包含规则名称和描述性详细信息。
  • events：使用事件变量定义数据源和过滤条件。
  • match：设置时间范围和用于桥接事件的占位符变量。
  • outcome：捕获提醒的其他上下文。多事件规则需要聚合函数。
  • condition：指定规则触发时必须存在的事件变量。

如需构建多事件规则，请执行以下操作：

  1. 定义事件变量：在 events 部分中，定义 $e1 以捕存 "PROCESS_LAUNCH" 事件，并定义 $e2 以捕获特定恶意文件哈希。
  2. 与占位符关联：使用 $user 占位符变量，通过共享的主用户 ID 将这两个不同的事件流关联起来（例如 $user = $e1.principal.user.userid and $user = $e2.principal.user.userid）。
  3. 对匹配项进行分组：在 match 部分中，您指定这些事件必须在设定的时间窗口（例如 5 分钟 (5m)）内为同一 $user 发生。

示例：构建多事件规则

  • 在以下示例中，$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
}

以下规则组件描述了示例中使用的逻辑：

  • 事件变量：定义了两个事件变量 $e1 和 $e2。使用了占位符变量 $user，根据常见的 userid 字段联接这些事件。
  • match 部分：为此多事件规则添加了 match 部分，以便按用户分组并指定 跳跃时间窗口（5 分钟 (5m)）来关联事件。
  • condition 部分：定义了触发提醒的逻辑。如果存在第一个事件或第二个事件，此示例会触发提醒。

使用其他工具构建查询

这些工具是编写、验证和加速 YARA-L 采用的必备工具：

  • UDM 查找工具：直接在界面中快速搜索和引用 UDM 字段名称、定义和数据类型。如果字段 ID 未知，请优先检查此引用。
  • 自然语言到 YARA-L 搜索：在搜索栏中，输入说明以起草初始查询，或获取或翻译相应的 YARA-L 建议。
  • SPL → YARA-L 转换器（实验室工具）：如果您要从竞争对手平台过渡，请使用此工具（可在实验室 部分中找到）将旧版 Splunk SPL 查询转换为 YARA-L。这会生成结构化的起点，从而加快迁移速度并优化检测逻辑。如需使用实验室工具，请在 Google SecOps 中前往 yourinstancename.chronicle.security/labs。

后续步骤

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