Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

开发解析器扩展程序

支持范围：

Google SecOps SIEM

本文档介绍了如何创建解析器扩展程序，以从原始日志数据中提取字段，并将其映射到 Google Security Operations 平台中的目标 UDM（统一数据模型）字段。

本文档概述了解析器扩展程序的创建流程：

创建解析器扩展程序。
前提条件和限制。
识别原始日志数据中的源字段。
选择适当的目标 UDM 字段。
选择合适的解析器扩展程序定义方法：

定义解析器扩展程序包括设计解析逻辑以过滤原始日志数据、转换数据并将其映射到目标 UDM 字段。 Google SecOps 提供了两种创建解析器扩展程序的方法：
- 使用无代码（映射数据字段）方法创建解析器扩展程序。
- 使用代码段方法创建解析器扩展程序。
针对各种日志格式和场景的解析器扩展程序创建示例。例如，使用 JSON 的无代码示例，以及用于复杂逻辑或非 JSON 格式（CSV、XML、Syslog）的代码段。

创建解析器扩展程序

解析器扩展程序提供了一种灵活的方式来扩展现有默认（和自定义）解析器的功能。解析器扩展程序提供了一种灵活的方式，可在不替换现有默认（或自定义）解析器的情况下扩展其功能。借助扩展程序，您可以通过添加新的解析逻辑、提取和转换字段以及更新或移除 UDM 字段映射来自定义解析器流水线。

解析器扩展程序与自定义解析器不同。您可以为没有默认解析器的日志类型创建自定义解析器，也可以选择不接收解析器更新。

解析器提取和标准化流程

Google SecOps 会以原始日志的形式接收原始日志数据。默认（和自定义）解析器会将核心日志字段提取并标准化为 UDM 记录中的结构化 UDM 字段。这仅代表原始日志数据的一部分。您可以定义解析器扩展程序，以提取默认解析器未处理的日志值。解析器扩展程序激活后，会成为 Google SecOps 数据提取和标准化流程的一部分。

注入和标准化工作流

定义新的解析器扩展程序

默认解析器包含预定义的映射指令集，这些指令指定了如何提取、转换和标准化核心安全值。您可以使用无代码（映射数据字段）方法或代码段方法定义映射指令，从而创建新的解析器扩展程序：

无需代码的方法

无代码方法最适合从原生 JSON、XML 或 CSV 格式的原始日志中进行简单提取。借助该功能，您可以指定原始日志来源字段并映射相应的目标 UDM 字段。

例如，使用简单的等式比较来提取最多包含 10 个字段的 JSON 日志数据。
代码段方法

通过代码段方法，您可以定义指令，以从原始日志中提取和转换值，并将其分配给 UDM 字段。代码段使用与默认（或自定义）解析器相同的类似 Logstash 的语法。

此方法适用于所有受支持的日志格式。它最适合以下场景：
- 复杂的数据提取或复杂逻辑。
- 需要基于 Grok 的解析器的非结构化数据。
- 非 JSON 格式，例如 CSV 和 XML。
代码段使用函数从原始日志数据中提取特定数据。例如，Grok、JSON、KV 和 XML。

在大多数情况下，最好使用默认（或自定义）解析器中使用的数据映射方法。

将新提取的值合并到 UDM 字段中

激活后，解析器扩展程序会根据预定义的合并原则，将新提取的值合并到相应 UDM 记录中的指定 UDM 字段。例如：

覆盖现有值：提取的值会覆盖目标 UDM 字段中的现有值。

唯一的例外是重复字段，您可以配置解析器扩展程序，以便在将数据写入 UDM 记录中的重复字段时附加新值。
解析器扩展优先：解析器扩展中的数据映射指令优先于该日志类型的默认（或自定义）解析器中的数据映射指令。如果映射指令存在冲突，解析器扩展程序将覆盖默认设置的值。

例如，如果默认解析器将原始日志字段映射到 event.metadata.description UDM 字段，而解析器扩展程序将其他原始日志字段映射到同一 UDM 字段，则解析器扩展程序会覆盖默认解析器设置的值。

重复字段选择器

在“映射数据字段（无代码）”和“编写代码段”方法中，您都可以控制解析器扩展程序如何将值保存到重复字段（支持值数组的字段，例如 principal.ip）。在扩展程序（扩展程序定义）面板中，使用重复字段字段，该字段提供附加值和替换值选项。

附加与替换行为

某些 UDM 字段存储着由值组成的数组，例如 principal.ip 字段。借助重复字段选择器，您可以控制解析器扩展程序如何在重复字段中存储新提取的数据：

附加值：

解析器扩展程序会将新提取的值附加到 UDM 字段中的现有值数组。
替换值：

解析器扩展程序会将 UDM 字段中的现有值数组替换为新提取的值。

仅当重复字段位于层次结构的最低级别时，解析器扩展程序才能将数据映射到重复字段。例如：

支持将值映射到 udm.principal.ip，因为重复的 ip 字段位于层次结构的最低级层，而 principal 不是重复字段。
不支持将值映射到 udm.intermediary.hostname，因为 intermediary 是重复字段，并且不位于层次结构的最低级层。

下表提供了重复字段选择器配置如何影响生成的 UDM 记录的示例。

重复字段选择	日志示例	解析器扩展程序配置	生成的结果
附加值	`{"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"1.1.1.1, 2.2.2.2"}}}`	前提条件字段：`protoPayload.requestMetadata.callerIp` 前提条件值：`" "` 前提条件运算符：`NOT_EQUALS` 原始数据字段：`protoPayload.requestMetadata.callerIp` 目标字段：`event.idm.read_only_udm.principal.ip`	`metadata:{event_timestamp:{}.....}principal:{Ip:"1.1.1.1, 2.2.2.2"} } }`
附加值	`{"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2, 3.3.3.3", "name":"Akamai Ltd"}}}`	前提条件 1：前提条件字段：`protoPayload.requestMetadata.callerIp` 前提条件值：`" "` 前提条件运算符：`NOT_EQUALS` 原始数据字段：`protoPayload.requestMetadata.callerIp` 目标字段：`event.idm.read_only_udm.principal.ip` 前提条件 2：原始数据字段：`protoPayload.requestMetadata.name` 目标字段：`event.idm.read_only_udm.metadata.product_name`	应用扩展程序之前由预构建解析器生成的事件。 `metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}` 应用扩展程序后的输出。 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} .... product_name: "Akamai Ltd"}principal:{ip:"1.1.1.1, 2.2.2.2, 3.3.3.3"}}}`
替换值	`{"protoPayload":{"@type":"type..AuditLog","authenticationInfo":{"principalEmail":""},"requestMetadata":{"callerIp":"2.2.2.2"}}}`	前提条件字段：`protoPayload.authenticationInfo.principalEmail` 前提条件值：`" "` 前提条件运算符：`NOT_EQUALS` 原始数据字段：`protoPayload.authenticationInfo.principalEmail` 目标字段：`event.idm.read_only_udm.principal.ip`	应用扩展程序之前由预构建解析器生成的 UDM 事件。 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}` 应用扩展程序后的 UDM 输出 `timestamp:{} idm:{read_only_udm:{metadata:{event_timestamp:{} ....} principal:{ip:"2.2.2.2"}}}`

限制

每种日志类型一个解析器扩展程序：您只能为每种日志类型创建一个解析器扩展程序。
仅限一种数据映射指令方法：您可以使用无代码方法或代码段方法构建解析器扩展程序，但不能同时使用这两种方法。
用于验证的日志示例：需要过去 30 天内的日志示例来验证 UDM 解析器扩展程序。如需了解详情，请参阅确保日志类型有有效的解析器。
基本解析器错误：基本解析器错误无法在解析器扩展程序中识别或修复。
重复字段处理：在特定扩展程序中，您只能使用一种方法（附加或替换）。替换整个重复对象时请务必小心，以免意外丢失数据。
Additional.fields 被解释为一组键值对，而不是重复字段：因此，您可以通过将解析器的 UDM 映射和扩展程序的 UDM 输出各自的键值对添加到该组中，无缝地将它们组合在一起。
消除歧义的事件：解析器扩展程序无法处理单个记录中包含多个唯一事件的日志，例如 Google 云端硬盘数组。
XML 和无代码：XML 不支持无代码模式。请改用代码段方法。
解析器语法与 YARA-L 检测规则：注入解析器和解析器扩展程序在注入时使用 Logstash Grok 和配置语法以及过滤条件（例如 grok、mutate、json、date 和 base64）将原始日志解析为统一数据模型 (UDM)。解析器无法使用 YARA-L 语法、结果块或生成器函数（例如 yield）。YARA-L 2.0 严格来说是一种检测引擎查询语言，在下游对标准化 UDM 事件进行评估，以发出威胁提醒，但无法解析原始日志、更改 UDM 字段或丢弃传入的日志流量。
默认情况下仅向前应用：默认情况下，解析器扩展程序仅从激活时起应用于新注入的日志。如果因关键业务需求而需要使用更新后的映射重新解析历史日志，您可以通过 Google Cloud 支持团队请求后端日志重放任务。如需了解详情，请参阅重新解析历史数据（日志重放）。
解析器逻辑中无法访问注入标签：解析器扩展程序无法读取注入标签 (metadata.ingestion_labels) 以将值映射到 UDM 字段，因为解析器在沙盒化执行环境中运行，只能查看原始日志正文。
采用无代码方法的预留关键字：如果日志包含以下任何预留关键字，请使用代码段方法，而不是无代码方法：
- collectionTimestamp
- createTimestamp
- enableCbnForLoop
- event
- filename
- message
- namespace
- output
- onErrorCount
- timestamp
- timezone
移除现有映射：您只能使用代码段方法移除现有 UDM 字段映射。
无法使用扩展程序移除主机名 UDM 字段的映射：您无法使用扩展程序取消设置（移除）主机名 UDM 字段（例如 principal.hostname）的映射。

解析器概念

以下文档介绍了重要的解析器概念：

前提条件

创建解析器扩展程序的前提条件：

日志类型必须有有效的默认（或自定义）解析器。
Google SecOps 必须能够使用默认（或自定义）解析器注入和标准化原始日志。
确保目标日志类型的有效默认（或自定义）解析器在过去 30 天内提取了原始日志数据。此数据应包含您打算提取或用于过滤日志记录的字段示例。它将用于验证您的新数据映射指令。

开始使用

在创建解析器扩展程序之前，请执行以下操作：

验证前提条件：

确保日志类型有有效的解析器。如果它还没有解析器，请创建一个自定义解析器。
确定要从原始日志中提取的字段：

确定要从原始日志中提取的字段。
选择适当的 UDM 字段：

选择适当的对应 UDM 字段，以映射提取的原始日志字段。
选择解析器扩展程序定义方法：

选择两种扩展方法（数据映射方法）中的一种来创建解析器扩展。

验证前提条件

确保您要扩展的日志类型具有有效的解析器，如以下部分所述：

确保日志类型有有效的解析器

确保您要扩展的日志类型具有有效的默认（或自定义）解析器。

在以下列表中搜索您的日志类型：

具有默认解析器的受支持日志类型。
- 如果日志类型有默认解析器，请确保解析器处于活跃状态。
- 如果日志类型没有默认解析器，请确保日志类型有自定义解析器。
没有默认解析器的受支持日志类型。
- 如果日志类型没有默认解析器，请确保日志类型有自定义解析器。

确保日志类型有自定义解析器

如需确保日志类型有自定义解析器，请执行以下操作：

在导航栏中，依次选择设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。
在解析器表中搜索要扩展的日志类型。
- 如果该日志类型尚无默认或自定义解析器，请点击添加新解析器（或创建解析器），然后按照根据映射说明创建自定义解析器中的步骤操作。
- 如果该日志类型已有自定义解析器，请确保该解析器处于活跃状态。

确保解析器对日志类型有效

如需检查解析器是否对某种日志类型处于活跃状态，请执行以下步骤：

在导航栏中，依次选择设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。
在解析器表中搜索要扩展的日志类型。

如果日志类型的解析器未处于活跃状态，请将其激活：
- 如需了解默认解析器，请参阅管理预构建解析器更新。
- 如需了解自定义解析器，请参阅配置自定义解析器。

确定要从原始日志中提取的字段

分析要从中提取数据的原始日志，以确定默认（或自定义）解析器未提取的字段。请注意默认（或自定义）解析器如何提取原始日志字段并将其映射到相应的 UDM 字段。

如需确定要从原始日志中提取的特定字段，您可以使用搜索工具来确定这些字段：

如需访问搜索工具，请依次前往调查 > SIEM 搜索。在搜索查询前输入 raw=。如需了解详情，请参阅搜索原始日志。
如需访问旧版搜索工具，请点击 SIEM 搜索页面顶部的前往旧版搜索。如需了解详情，请参阅旧版方法：使用原始日志搜索提示。

如需详细了解如何在原始日志中进行搜索，请参阅：

选择适当的 UDM 字段

现在，您已确定要提取的特定目标字段，接下来可以将它们与相应的目标 UDM 字段进行匹配。在原始日志来源字段与其目标 UDM 字段之间建立清晰的映射。您可以将数据映射到支持标准数据类型或重复字段的任何 UDM 字段。

选择正确的 UDM 字段

以下资源有助于简化此流程：

熟悉 UDM 的主要概念
了解现有解析器使用的数据映射
使用 UDM 查找工具查找与源字段匹配的潜在 UDM 字段。
用于解析器数据映射的重要 UDM 字段指南包含 UDM 架构最常用字段的摘要和说明。
统一数据模型字段列表包含所有 UDM 字段及其说明的列表。重复字段在列表中通过 "repeated" 标签进行标识。
避免错误的重要 UDM 注意事项

熟悉 UDM 的主要概念

逻辑对象：事件和实体

UDM 架构描述了存储数据的所有可用属性。每条 UDM 记录都描述了一个事件或实体。数据存储在不同的字段中，具体取决于记录描述的是事件还是实体。
- UDM 事件对象存储环境中发生的操作的相关数据。原始事件日志描述了设备（例如防火墙或 Web 代理）记录的操作。
- UDM 实体对象存储区存储有关 UDM 事件中涉及的参与者或实体的数据，例如环境中的资产、用户或资源。
UDM 事件的结构
UDM 实体的结构

UDM 名词：名词表示 UDM 事件中的参与者或实体。例如，名词可以是执行事件中所述活动的用户或设备。名词也可以是事件中所述活动的目标设备或用户。

UDM 名词	说明
`principal`	负责发起事件中所述操作的实体。
`target`	作为操作的接收者或对象的实体。在防火墙连接中，接收连接的机器就是目标。
`src`	主账号对其执行操作的来源实体。例如，如果用户将文件从一台机器复制到另一台机器，则该文件及其来源机器将表示为 src。
`intermediary`	在事件中充当中间人的任何实体，例如代理服务器。它们可以影响操作，例如屏蔽或更改请求。
`observer`	监控和报告事件但不直接与流量交互的实体。例如，网络入侵检测系统或安全信息和事件管理系统。
`about`	事件中涉及的不属于上述类别的任何其他实体。例如，电子邮件附件或进程启动期间加载的 DLL。

在实践中，主体和目标 Noun 对象是最常用的对象。另请注意，上述说明构成了 Nouns 的推荐用法。实际用量可能会因默认或自定义基本解析器的实现而异。

了解现有解析器使用的数据映射

建议您了解默认（或自定义）解析器使用的现有数据映射，即原始日志来源字段与其目标 UDM 字段之间的映射。

如需查看现有默认（或自定义）解析器中使用的原始日志来源字段与目标 UDM 字段之间的数据映射，请执行以下操作：

在导航栏中，依次选择设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。
在解析器表中搜索要扩展的日志类型。
前往该行，然后依次点击菜单 > 查看。

在预构建（或自定义）标签页中，解析器代码部分会显示现有默认（或自定义）解析器中使用的原始日志来源字段与目标 UDM 字段之间的数据映射。

使用 UDM 查询工具

使用 UDM 查找工具帮助识别与原始日志来源字段匹配的 UDM 字段。

Google SecOps 提供了 UDM 查找工具，可帮助您快速找到目标 UDM 字段。如需访问 UDM 查找工具，请依次前往调查 > SIEM 搜索。

如需详细了解如何使用 UDM 查找工具，请参阅以下主题：

UDM 查询工具示例

例如，如果原始日志中有一个名为“packets”的来源字段，请使用 UDM 查找工具查找名称中包含“packets”的潜在目标 UDM 字段：

依次前往调查 > SIEM 搜索。
在 SIEM 搜索页面中，点击 UDM 查找。

UDM 查找对话框随即打开。搜索工具会按字段名称或字段值匹配 UDM 字段：
- 按字段名称查找 - 将您输入的文本字符串与包含该文本的字段名称进行匹配。
- 按字段值查找 - 将您输入的值与存储的日志数据中包含该值的字段进行匹配。
在 UDM 查找对话框中，在查找 UDM 字段/值字段中输入“packets”，然后选择 UDM 字段。

搜索功能将显示 UDM 字段名称中包含文本“packets”的潜在 UDM 字段列表。
逐一点击各行，查看每个 UDM 字段的说明。

避免错误的重要 UDM 注意事项

外观相似的字段：UDM 的分层结构可能会导致字段名称相似。如需获取指导，请参阅默认解析器。如需了解详情，请参阅了解现有解析器使用的数据映射。
任意字段映射：对于无法直接映射到 UDM 字段的数据，请使用 additional 对象。如需了解详情，请参阅将任意字段映射到 UDM。
重复字段：在代码段中使用重复字段时要小心。替换整个对象可能会覆盖原始数据。使用无代码方法可以更好地控制重复字段。如需了解详情，请参阅重复字段选择器。
UDM 事件类型的强制性 UDM 字段：将 UDM metadata.event_type 字段分配给 UDM 记录时，每个 event_type 都需要在 UDM 记录中存在一组不同的相关字段。如需了解详情，请参阅详细了解如何分配 UDM metadata.event_type 字段。
基本解析器问题：解析器扩展程序无法修复基本解析器中的错误。基础解析器是创建 UDM 记录的默认（或自定义）解析器。考虑各种选项，例如增强解析器扩展程序、修改基本解析器或预过滤日志。

将任意字段映射到 UDM

如果找不到合适的标准 UDM 字段来存储数据，请使用 additional 对象将数据存储为自定义键值对。这样，您就可以在 UDM 记录中存储有价值的信息，即使该信息没有匹配的 UDM 字段。

选择解析器扩展程序定义方法

在选择解析器扩展程序定义方法之前，您必须先完成以下部分：

创建解析器扩展程序
开始

后续步骤是打开解析器扩展程序页面，并选择用于定义解析器扩展程序的扩展程序方法：

打开“解析器扩展程序”页面

您可以在解析器扩展程序页面上定义新的解析器扩展程序。

您可以通过以下方式打开解析器扩展程序页面：从设置菜单、原始日志搜索或旧版原始日志搜索：

从“设置”菜单中打开

如需从设置菜单打开解析器扩展程序页面，请执行以下操作：

在导航栏中，依次选择设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。

解析器表按日志类型显示默认解析器列表。
找到要扩展的日志类型，依次点击菜单 > 扩展解析器 > 创建扩展程序。

解析器扩展程序页面随即打开。

从原始日志搜索中打开

如需从原始日志搜索打开解析器扩展程序页面，请执行以下操作：

依次前往调查 > SIEM 搜索。
在搜索字段中，为搜索参数添加前缀 raw =，并将搜索字词用英文引号括起来。例如 raw = "example.com"。
点击运行搜索。结果会显示在原始日志面板中。
点击原始日志面板中的日志（行）。系统会显示事件查看器面板。
点击事件查看器面板中的原始日志标签页。系统会显示原始日志。
依次点击管理解析器 > 扩展解析器 > 创建扩展程序（或依次选择创建扩展程序 > 下一步）。

解析器扩展程序页面随即打开。

从旧版原始日志搜索中打开

如需从旧版原始日志搜索打开解析器扩展程序页面，请执行以下操作：

使用旧版原始日志搜索来搜索与要解析的记录类似的记录。
从时间轴面板中选择一个事件（或点击原始日志图标），即可打开原始日志。
依次点击管理解析器 > 扩展解析器 > 创建扩展程序（或依次选择创建扩展程序 > 下一步）。

解析器扩展程序页面随即打开。

“解析器扩展程序”页面

该页面会显示原始日志和扩展程序（扩展程序定义）面板：

原始日志面板：

系统会显示所选日志类型的原始日志数据示例。如果您从原始日志搜索打开该页面，则示例数据是搜索结果。您可以使用查看方式菜单（原始、JSON、CSV、XML 或十六进制/ASCII）和自动换行复选框来设置示例的格式。
1. 检查显示的原始日志数据样本是否代表解析器扩展程序将处理的日志。
2. 点击预览 UDM 输出（或显示 UDM 输出），查看示例原始日志数据的 UDM 输出。
扩展程序（扩展程序定义）面板：

这样，您就可以使用以下两种映射指令方法之一来定义解析器扩展程序：映射数据字段（无代码）或编写代码段（或编写代码段）。您不能在同一解析器扩展程序中同时使用这两种方法。

根据您选择的方法，您可以指定要从传入的原始日志中提取的源日志数据字段，并将其映射到相应的 UDM 字段，也可以编写代码段来执行这些任务以及更多任务。

选择扩展方法

在解析器扩展程序页面的扩展程序面板中，在扩展程序方法字段中，选择以下方法之一来创建解析器扩展程序：

映射数据字段（无代码）方法：

通过这种方法，您可以指定原始日志中的字段，并将其映射到目标 UDM 字段。

此方法适用于以下原始日志格式：
- 原生 JSON、原生 XML 或 CSV。
- Syslog 标头加上原生 JSON、原生 XML 或 CSV。您可以为以下格式的原始日志创建数据字段类型映射指令：JSON、XML、CSV、SYSLOG + JSON、SYSLOG + XML 和 SYSLOG + CSV。
请参阅后续步骤：创建无代码（映射数据字段）指令。
编写代码段（或编写代码段）方法：

通过这种方法，您可以使用类似 Logstash 的语法来指定指令，以便从原始日志中提取值并进行转换，然后将这些值分配给 UDM 记录中的 UDM 字段。
- 代码段使用与默认（或自定义）解析器相同的语法和部分。如需了解详情，请参阅解析器语法。
- 此方法适用于该日志类型的所有受支持的数据格式。
请参阅后续步骤：创建代码段说明。

创建无代码（映射数据字段）说明

无代码方法（也称为映射数据字段方法）可让您指定原始日志字段的路径，并将其映射到相应的目标 UDM 字段。

在使用无代码方法创建解析器扩展程序之前，您必须先完成以下部分：

创建解析器扩展程序
开始
选择扩展方法，然后选择映射数据字段选项。

定义解析器扩展程序的后续步骤如下：

设置“重复字段”选择器
为每个字段定义数据映射指令
提交并激活解析器扩展程序

为每个字段定义数据映射指令

为要从原始日志中提取的每个字段定义数据映射指令。该指令应指定原始日志中源字段的路径，并将其映射到目标 UDM 字段。

如果原始日志面板中显示的原始日志示例包含 Syslog 标头，则会显示 Syslog 和目标字段。（某些日志格式不包含 Syslog 标头，例如原生 JSON、原生 XML 或 CSV。）

Google SecOps 需要 Syslog 和目标字段来预处理 Syslog 标头，以提取日志的结构化部分。
1. 定义以下字段：
  - Syslog：这是一个用户定义的模式，用于预处理 Syslog 标头并将其与原始日志的结构化部分分开。
    
    使用 Grok 和正则表达式指定提取模式，以标识 Syslog 标头和原始日志消息。如需了解详情，请参阅定义 Syslog 提取器字段。
  - 目标：Syslog 字段中存储日志结构化部分的变量名称。
    
    在提取模式中指定用于存储日志结构化部分的变量名称。
  以下是 Syslog 和 Target 字段的提取模式和变量名称示例。
2. 在系统日志和目标字段中输入值后，点击验证按钮。
  
  验证过程会检查语法和解析错误，然后返回以下任一结果：
  - 成功：系统会显示数据映射字段。定义解析器扩展程序的其余部分。
  - 失败：系统会显示一条出错提示。请先更正错误，然后再继续。
您可以视需要定义前提条件指令。

前提条件指令通过将静态值与原始日志中的字段进行匹配，来标识解析器扩展程序处理的原始日志子集。如果传入的原始日志满足前提条件，则解析器扩展程序会应用映射指令。如果值不匹配，解析器扩展程序不会应用映射指令。

填写以下字段：
- 前提条件字段（对于 CSV，为前提条件列）：原始日志中包含要比较的值的字段标识符。如果日志数据格式为 JSON 或 XML，请输入该字段的完整路径；如果数据格式为 CSV，请输入列位置。
- 前提条件运算符：选择等于或不等于。
- 前提条件值：将与原始日志中的前提条件字段进行比较的静态值。
如需查看前提条件指令的另一个示例，请参阅无代码 - 提取具有前提条件值的字段。
将原始日志数据字段映射到目标 UDM 字段：
- 原始数据字段（对于 CSV，则为原始数据列）：如果日志数据格式为 JSON（例如：jsonPayload.connection.dest_ip）或 XML（例如：/Event/Reason-Code），请输入字段的完整路径；如果数据格式为 CSV，请输入列位置（注意：索引位置从 1 开始）。
- 目标字段：输入将存储值的完全限定 UDM 字段名称，例如 udm.metadata.collected_timestamp.seconds。
重要提示：如果原始日志采用 JSON 格式，则日志值的数据类型必须与其对应的目标 UDM 字段的数据类型一致。例如，如果日志将 packets sent 记录为字符串 ("packets_sent":"16")，并且您尝试将其映射到具有 uint64 数据类型的 network.sent_bytes UDM 字段，则指令将失败。此要求不适用于 CSV 和 XML 格式的日志。
如需继续添加更多字段，请点击添加，然后输入下一个字段的所有映射指令详细信息。

如需查看映射字段的另一个示例，请参阅无代码 - 提取字段。

提交并激活解析器扩展程序

为要从原始日志中提取的所有字段定义数据映射指令后，提交并激活解析器扩展程序。

点击提交，保存并验证映射指令。

Google SecOps 会验证映射指令：

如果验证过程成功，状态会更改为Live，并且映射指令会开始处理传入的日志数据。

如果验证流程失败，状态会更改为失败，并且“原始日志”字段中会显示错误。

以下是验证错误示例：

  ERROR: generic::unknown: pipeline.ParseLogEntry failed: LOG_PARSING_CBN_ERROR:
  "generic::invalid_argument: pipeline failed: filter mutate (7) failed: copy failure:
  copy source field \"jsonPayload.dest_instance.region\" must not be empty
  (try using replace to provide the value before calling copy)

  "LOG: {"insertId":"14suym9fw9f63r","jsonPayload":{"bytes_sent":"492",
  "connection":{"dest_ip":"10.12.12.33","dest_port":32768,"protocol":6,
  "src_ip":"10.142.0.238","src_port":22},"end_time":"2023-02-13T22:38:30.490546349Z",
  "packets_sent":"15","reporter":"SRC","src_instance":{"project_id":"example-labs",
  "region":"us-east1","vm_name":"example-us-east1","zone":"us-east1-b"},
  "src_vpc":{"project_id":"example-labs","subnetwork_name":"default",
  "vpc_name":"default"},"start_time":"2023-02-13T22:38:29.024032655Z"},
  "logName":"projects/example-labs/logs/compute.googleapis.com%2Fvpc_flows",
  "receiveTimestamp":"2023-02-13T22:38:37.443315735Z","resource":{"labels":
  {"location":"us-east1-b","project_id":"example-labs",
    "subnetwork_id":"00000000000000000000","subnetwork_name":"default"},
    "type":"gce_subnetwork"},"timestamp":"2023-02-13T22:38:37.443315735Z"}

解析器扩展程序的生命周期状态

解析器扩展程序具有以下生命周期状态：

DRAFT：新创建但尚未提交的解析器扩展程序。
VALIDATING：Google SecOps 正在根据现有原始日志验证映射指令，以确保字段解析无误。
LIVE：解析器扩展程序已通过验证，现已投入生产。它会从传入的原始日志中提取数据并将其转换为 UDM 记录。
FAILED：解析器扩展程序未通过验证。

详细了解 Syslog 提取器字段

通过 Syslog 提取器字段，您可以定义 Grok、正则表达式以及正则表达式模式中用于存储输出的命名令牌，从而将 Syslog 标头与结构化日志分开。

定义 Syslog 提取器字段

Syslog 和目标字段中的值共同定义解析器扩展程序如何将 Syslog 标头与原始日志的结构化部分分开。在Syslog字段中，您可以使用 Grok 和正则表达式语法的组合来定义表达式。该表达式包含一个变量名称，用于标识原始日志的结构化部分。在目标字段中，指定该变量名称。

以下示例说明了这些字段如何协同工作。

以下是原始日志示例：

<13>1 2022-09-14T15:03:04+00:00 fieldname fieldname - - - {"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

原始日志包含以下部分：

Syslog 标头：<13> 2022-09-14T15:03:04+00:00 fieldname fieldname - - -
JSON 格式的事件：{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

如需将 Syslog 标头与原始日志的 JSON 部分分开，请在 Syslog 字段中使用以下示例表达式：%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}

表达式的这一部分用于标识 Syslog 标头： %{TIMESTAMP\_ISO8601} %{WORD} %{WORD} ([- ]+)?
表达式的这一部分会捕获原始日志的 JSON 段： %{GREEDYDATA:msg}

此示例包含变量名称 msg。您可以自行选择变量名称。解析器扩展程序会提取原始日志的 JSON 段，并将其分配给变量 msg。

在目标字段中，输入变量名称 msg。存储在 msg 变量中的值会输入到您在解析器扩展程序中创建的数据字段映射指令中。

使用原始日志示例，以下片段是数据映射指令的输入：

{"timestamp": "2021-03-14T14:54:40.842152+0000","flow_id": 1885148860701096, "src_ip": "10.11.22.1","src_port": 51972,"dest_ip": "1.2.3.4","dest_port": 55291,"proto": "TCP"}

以下显示了已完成的系统日志和目标字段：

Syslog 提取器字段

下表提供了更多示例，其中包含示例日志、Syslog 提取模式、目标变量名称和结果。

原始日志示例	Syslog 字段	目标字段	结果
`<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}"`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg}`	msg	`field_mappings { field: "msg" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }`
`<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:msg1} ([- ]+)?%{GREEDYDATA:msg2}`	msg2	`field_mappings { field: "msg2" value: "{\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}" }`
`"<13>1 2022-07-14T15:03:04+00:00 suricata suricata - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\"} - - - {\"timestamp\": \"2021-03-14T14:54:40.842152+0000\",\"flow_id\": 1885148860701096,\"in_iface\": \"enp94s0\",\"event_type\": \"alert\",\"vlan\": 522,\"src_ip\": \"1.1.2.1\",\"src_port\": 51972,\"dest_ip\": \"1.2.3.4\",\"dest_port\": 55291,\"proto\": \"TCP\"}"`	`%{TIMESTAMP_ISO8601} %{WORD} %{WORD} ([- ]+)?%{GREEDYDATA:message} ([- ]+)?%{GREEDYDATA:msg2}`	msg2	`Error - message already exists in state and not overwritable.`

详细了解如何分配 UDM `metadata.event_type` 字段

将 UDM metadata.event_type 字段分配给 UDM 记录时，系统会对其进行验证，以确保 UDM 记录中存在所需的相关字段。每个 UDM metadata.event_type 都需要一组不同的相关字段，例如，没有 user 的 USER_LOGIN 事件没有用。

如果缺少必需的相关字段，UDM 验证会返回错误：

  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }

Grok 解析器会返回更详细的错误：

  generic::unknown:
  invalid event 0: LOG_PARSING_GENERATED_INVALID_EVENT:
  "generic::invalid_argument: udm validation failed: target field is not set"

如需查找要分配的 UDM event_type 的必填字段，请使用以下资源，其中采用指南通过提供填充给定 UDM metadata.event_type 所需的最低强制性 UDM 字段来补充 UDM 使用指南。

例如，打开文档并搜索 GROUP_CREATION 事件类型。

您应该会看到以下最少 UDM 字段，这些字段以 UDM 对象的形式呈现：

  {
      "metadata": {
          "event_timestamp": "2023-07-03T13:01:10.957803Z",
          "event_type": "GROUP_CREATION"
      },
      "principal": {
          "user": {
              "userid": "pinguino"
          }
      },
      "target": {
          "group": {
              "group_display_name": "foobar_users"
          }
      }
  }

创建代码段说明

通过代码段方法，您可以使用类似 Logstash 的语法来定义如何从原始日志中提取和转换值，并将其分配给 UDM 记录中的 UDM 字段。

在使用代码段方法创建解析器扩展程序之前，您必须先完成以下部分：

创建解析器扩展程序
开始
选择扩展程序方法，然后选择 编写代码段选项。

定义解析器扩展程序的后续步骤如下：

如需了解相关提示和最佳实践，请参阅编写代码段指令时的提示和最佳实践。
创建代码段指令
提交代码段说明

编写代码段指令时的提示和最佳实践

代码段指令可能会因 Grok 模式不正确、重命名或替换操作失败或语法错误等问题而失败。请参阅以下内容，了解相关提示和最佳实践：

创建代码段指令

代码段指令使用与默认（或自定义）解析器相同的语法和部分：

第 1 部分。从原始日志中提取数据。
第 2 部分。转换提取的数据。
第 3 部分。为 UDM 字段分配一个或多个值。
第 4 部分。将 UDM 事件字段绑定到 @output 键。

如需使用代码段方法创建解析器扩展程序，请执行以下操作：

在解析器扩展程序页面的 CBN 代码段面板中，输入代码段以创建解析器扩展程序。
点击验证以验证映射指令。

代码段指令示例

以下示例展示了一个代码段。

以下是原始日志示例（为简洁起见，省略了其他 jsonPayload 字段）：

  {
      "insertId": "00000000",
      "jsonPayload": {
          "packets_sent": "4"
      },
      "timestamp": "2022-05-03T01:45:00.150614953Z"
  }

以下是将 jsonPayload.packets_sent 中的值映射到 network.sent_bytes UDM 字段的代码段示例：

filter {
  mutate {
    replace => {
      "jsonPayload.packets_sent" => ""
    }
  }
  # Section 1. extract data from the raw JSON log
  json {
    source => "message"
    array_function => "split_columns"
    on_error => "_not_json"
  }
  if [_not_json] {
    drop {
      tag => "TAG_UNSUPPORTED"
    }
  } else {
    # Section 2. transform the extracted data
    if [jsonPayload][packets_sent] not in ["", 0] {
      mutate {
        convert => {
          "jsonPayload.packets_sent" => "uinteger"
        }
        on_error => "_exception1"
      }
      # Section 3. assign the value to a UDM field
      mutate {
        Replace => {
          "event.idm.read_only_udm.network.sent_bytes" => "jsonPayload.packets_sent"
        }
        on_error => "_exception2"
      }
      if ![_exception1] and![_exception2] {
        # Section 4. Bind the UDM fields to the @output key
        mutate {
          merge => {
            "@output" => "event"
          }
        }
      }
    }
  }
}

提交代码段指令

点击提交以保存映射说明。
Google SecOps 会验证映射指令。
- 如果验证过程成功，状态会更改为Live，并且映射指令会开始处理传入的日志数据。
- 如果验证流程失败，状态会更改为失败，并且“原始日志”字段中会显示错误。
注意：在验证解析器扩展程序期间，您无法修改数据映射指令。

管理现有解析器扩展程序

您可以查看、修改、删除和控制对现有解析器扩展程序的访问权限。

查看现有解析器扩展程序

在导航栏中，依次选择设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。
在“解析器”列表中，找到要查看的解析器（日志类型）。具有解析器扩展程序的解析器会在其名称旁边显示 EXTENSION（或 EXTN）文本。
前往该行，然后依次点击菜单 > 扩展解析器 > 查看扩展。

系统会显示查看自定义/预构建解析器 > 扩展程序标签页（或扩展程序标签页），其中显示了解析器扩展程序的详细信息。摘要面板默认显示 LIVE 解析器扩展程序。

修改解析器扩展程序

打开查看自定义/预构建解析器 > 扩展程序标签页（或扩展程序标签页），如查看现有解析器扩展程序中所述。
点击修改扩展程序（或修改）按钮。

系统会显示解析器扩展程序页面。
修改解析器扩展程序。
- 如需取消修改并舍弃更改，请点击舍弃草稿（或舍弃扩展程序）。
- 如需随时删除解析器扩展程序，请点击删除失败的扩展程序（或删除扩展程序）。
- 完成解析器扩展程序的修改后，点击提交。
  
  系统会运行验证流程来验证新配置。
  
  注意：在验证解析器扩展程序期间，您无法修改数据映射指令。

删除解析器扩展程序

打开查看自定义/预构建解析器 > 扩展程序标签页（或扩展程序标签页），如查看现有解析器扩展程序中所述。
点击删除扩展程序按钮。

控制对解析器扩展程序的访问权限

默认情况下，拥有管理员角色的用户可以访问解析器扩展程序。您可以控制哪些人可以查看和管理解析器扩展程序。如需详细了解如何管理用户和群组或分配角色，请参阅基于角色的访问权限控制。

下表总结了 Google SecOps 中的新角色。

功能	操作	说明
解析器	删除	删除解析器扩展程序。
解析器	修改	创建和修改解析器扩展程序。
解析器	查看	查看解析器扩展程序。

使用解析器扩展程序移除 UDM 字段映射

您可以使用解析器扩展程序移除现有的 UDM 字段映射。

依次点击设置 > 数据管理 > 解析器。如果您使用的是仅限 SIEM 的平台，请依次前往设置 > 解析器。
使用以下任一方法查看解析器扩展程序页面：
- 对于现有扩展程序，请依次点击菜单 > 扩展解析器 > 查看扩展程序。
- 对于新的解析器扩展程序，请依次点击菜单 > 扩展解析器 > 创建扩展程序。
选择编写代码段作为扩展程序方法，以添加用于移除特定 UDM 字段值的自定义代码段。

对于现有扩展程序，请在扩展程序（或扩展程序）标签页中，点击修改扩展程序（或修改），然后添加代码段。

如需查看示例代码段，请参阅代码段 - 移除现有映射。
按照提交代码段说明中的步骤提交扩展程序。

时区处理和时间戳格式设置

Google SecOps 会将 RFC 3339 UTC 格式的时间戳标准化和序列化，精确到微秒 (YYYY-MM-DDTHH:MM:SS.ffffffZ)。如果源日志仅提供秒级精度，平台会自动用尾随零 (.000000Z) 填充缺失的小数位，以保持架构一致性。

如果事件时间戳早于提取时间 (ingested_timestamp < event_timestamp)，则通常是因为来源发出的本地挂钟时间戳没有 ISO 时区偏移量（默认为世界协调时间 [UTC]），或者存在时钟漂移。您可以使用以下任一方法解决时区不一致问题：

在解析器扩展程序中调整时间戳：在代码段解析器扩展程序中使用 date 过滤器来指定来源时区：

if [raw_log] =~ /EST/ {
  date {
    match => [ "timestamp_str", "MMM dd HH:mm:ss" ]
    timezone => "America/New_York"
    target => "event.metadata.event_timestamp"
  }
}

配置转发器收集器时区替换：依次前往设置 > 数据管理 > 转发器，修改目标收集器，启用替换时区，然后从时区菜单中选择来源 IANA 时区（例如 Europe/Paris），以便在注入期间自动调整时间戳。