此页面由 Cloud Translation API 翻译。

解析器扩展程序

支持的平台：

Google SecOps SIEM

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

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

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

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

创建解析器扩展程序

解析器扩展提供了一种灵活的方式来扩展现有默认（和自定义）解析器的功能。它们不会替换默认（和自定义）解析器，而是允许对解析器流水线进行无缝自定义，从而实现新的解析逻辑以及字段的提取、操作和映射。

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

解析器提取和标准化流程

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 字段，则解析器扩展程序会覆盖默认解析器设置的值。

限制

每种日志类型一个解析器扩展程序：您只能为每种日志类型创建一个解析器扩展程序。
只能使用一种数据映射指令方法：您可以使用无代码方法或代码段方法构建解析器扩展程序，但不能同时使用这两种方法。
用于验证的日志示例：验证 UDM 解析器扩展程序需要过去 30 天内的日志示例。如需了解详情，请参阅确保有适用于日志类型的有效解析器。
基本解析器错误：基本解析器错误无法在解析器扩展程序中识别或修复。
代码段中的重复字段：在代码段中替换整个重复对象时，请务必小心，以免意外丢失数据。如需了解详情，请参阅重复字段选择器的详细信息。
已解析的事件：解析器扩展程序无法处理单个记录中包含多个唯一事件的日志，例如 Google 云端硬盘数组。
XML 和无代码：由于可能存在编码问题，因此不建议将无代码方法用于 XML。对 XML 使用代码段方法。
没有追溯性数据：您无法追溯性地解析原始日志数据。

解析器概念

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

前提条件

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

必须有适用于日志类型的有效默认（或自定义）解析器。
Google SecOps 必须能够使用默认（或自定义）解析器提取和标准化原始日志。
确保目标日志类型的有效默认（或自定义）解析器在过去 30 天内已提取原始日志数据。这些数据应包含您打算提取或用于过滤日志记录的字段的示例。系统会使用该 ID 来验证您的新数据映射说明。

开始使用

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

验证前提条件：

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

确定要从原始日志中提取的字段。
选择适当的 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 名词：名词代表 UDM 事件中的参与者或实体。例如，名词可以是执行事件中所述的活动的设备或用户，也可以是作为事件中描述的此类活动的目标的设备或用户。

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

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

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

在导航栏中，依次选择 SIEM 设置 > 解析器。
在解析器表中搜索要扩展的日志类型。
前往相应行，然后依次点击 Menu（菜单）> View（视图）。

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

使用 UDM 查询工具

使用 UDM 查询工具可帮助您确定与原始日志来源字段匹配的 UDM 字段。

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

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

UDM 查询工具示例

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

依次前往调查 > SIEM 搜索。
在 SIEM Search 页面中，在按值查找 UDM 字段字段中输入“packets”，然后点击 UDM Lookup。

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

搜索功能会显示一个可能的 UDM 字段列表，其中 UDM 字段名称中包含文本“packets”。
依次点击各行，查看每个 UDM 字段的说明。

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

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

将任意字段映射到 UDM

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

选择解析器扩展定义方法

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

创建解析器扩展程序
开始

接下来，请打开解析器扩展页面，然后选择用于定义解析器扩展的扩展方法：

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

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

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

通过“设置”菜单打开

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

在导航栏中，依次选择 SIEM 设置 > 解析器。

解析器表会按日志类型显示默认解析器列表。
找到要扩展的日志类型，依次点击 Menu > Create Extension。

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

通过原始日志搜索打开

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

依次前往调查 > SIEM 搜索。
在搜索字段中，将前缀 raw = 添加到搜索参数，并将搜索字词括在引号中。例如 raw = "example.com"。
点击运行搜索。结果会显示在原始日志面板中。
点击原始日志面板中的某条日志（行）。系统随即会显示事件视图面板。
点击 Event View 面板中的 Raw Log 标签页。系统会显示原始日志。
依次点击 Manage Parser（管理解析器）> Create Extension（创建扩展程序）> Next（下一步）。

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

从旧版原始日志搜索打开

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

使用旧版原始日志搜索功能搜索与要解析的记录类似的记录。
依次选择事件 > 时间轴面板中的相应事件。
展开事件数据面板。
依次点击 Manage Parser（管理解析器）> Create Extension（创建扩展程序）> Next（下一步）。

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

“解析器扩展程序”页面

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

原始日志面板：

这会显示所选日志类型的示例原始日志数据。如果您是通过原始日志搜索打开此页面，则示例数据是搜索结果。您可以使用查看为菜单（“原始”“JSON”“CSV”“XML”等）和换行文本复选框设置示例的格式。
1. 检查显示的原始日志数据示例是否能代表解析器扩展程序将处理的日志。
2. 点击预览 UDM 输出，查看示例原始日志数据的 UDM 输出。
扩展程序定义面板：

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

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

选择扩展方法

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

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

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

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

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

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

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

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

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

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

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

设置“重复字段”选择器

在扩展程序定义面板的 Repeated Fields 字段中，设置解析器扩展程序应如何将值保存到重复字段（支持值数组的字段，例如 principal.ip）：

附加值：新提取的值会附加到 UDM 数组字段中存储的一组现有值。
替换值：新提取的值会替换 UDM 数组字段中之前由默认解析器存储的一组现有值。

重复字段选择器中的设置不会影响非重复字段。

如需了解详情，请参阅重复字段选择器详解。

为每个字段定义数据映射说明

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

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

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

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

填写以下字段：
- 前提条件字段：原始日志中包含要比较的值的字段标识符。如果日志数据格式为 JSON 或 XML，请输入字段的完整路径；如果数据格式为 CSV，请输入列位置。
- 前提条件运算符：选择 EQUALS 或 NOT EQUALS。
- 前提条件值：将与原始日志中的前提条件字段进行比较的静态值。
如需查看前提条件指令的其他示例，请参阅无代码 - 提取具有前提条件值的字段。
将原始日志数据字段映射到目标 UDM 字段：
- 原始数据字段：如果日志数据格式为 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 会验证映射说明：

如果验证流程成功，状态会更改为“有效”，映射说明会开始处理传入的日志数据。

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

以下是验证错误示例：

  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：解析器扩展程序未通过验证。

详细了解“重复字段”选择器

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

附加值：

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

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

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

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

下表提供了 Repeated Fields 选择器配置如何影响生成的 UDM 记录的示例。

重复字段选择	日志示例	解析器扩展程序配置	生成的结果
附加值	`{"protoPayload":{"@type":"type.AuditLog","authenticationInfo":{"principalEmail":"admin@cmmar.co"},"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":"admin@cmmar.co"},"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":"admin@cmmar.co"},"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"}}}`

详细了解 Syslog 提取器字段

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

定义 Syslog 提取器字段

Syslog 和 Target 字段中的值会协同工作，定义解析器扩展程序如何将 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 和 Target 字段：

Syslog 提取器字段

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

原始日志示例	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 的必填字段，请使用以下资源：

Google SecOps 文档：UDM 使用指南 - 每个事件类型的必填 UDM 字段和选填 UDM 字段

第三方非官方资源：UDM 事件验证

如果 UDM 使用指南缺少详细信息，本文档会提供填充给定 UDM metadata.event_type 所需的最低 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 代码段面板中，输入代码段以创建解析器扩展程序。
点击验证以验证映射说明。

代码段说明示例

以下示例展示了代码段。

以下是原始日志的示例：

  {
      "insertId": "00000000",
      "jsonPayload": {
          ...section omitted for brevity...
          "packets_sent": "4",
          ...section omitted for brevity...
      },
      "timestamp": "2022-05-03T01:45:00.150614953Z"
  }

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

mutate {
 replace => {
    "jsonPayload.packets_sent" => ""
 }
}
filter {
    # 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"
                }
            }
            # Section 3. assign the value to a UDM field
            mutate {
                copy => {
                    "udm.network.sent_bytes" => "jsonPayload.packets_sent"
                }
                on_error => "_exception"
            }
            if ![_exception] {
                # Section 4. Bind the UDM fields to the @output key
                mutate {
                    merge => {
                        "@output" => "event"
                    }
                }
            }
        }
    }
}

提交代码段说明

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

管理现有的解析器扩展程序

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

查看现有的解析器扩展程序

在导航栏中，依次选择 SIEM 设置 > 解析器。
在“解析器”列表中，找到要查看的解析器（日志类型）。具有解析器扩展名的解析器的名称旁边会显示 EXTENSION 文本。
前往相应行，然后依次点击 Menu > View Extension。

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

修改解析器扩展程序

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

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

删除解析器扩展程序

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

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

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

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

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

解析器扩展程序

创建解析器扩展程序

解析器提取和标准化流程

定义新的解析器扩展

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

限制

解析器概念

前提条件

开始使用

验证前提条件

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

确保有适用于日志类型的自定义解析器

确保针对日志类型启用了解析器

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

选择适当的 UDM 字段

选择正确的 UDM 字段

熟悉主要的 UDM 概念

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

使用 UDM 查询工具

UDM 查询工具示例

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

将任意字段映射到 UDM

选择解析器扩展定义方法

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

通过“设置”菜单打开

通过原始日志搜索打开

从旧版原始日志搜索打开

“解析器扩展程序”页面

选择扩展方法

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

设置“重复字段”选择器

为每个字段定义数据映射说明

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

详细了解“重复字段”选择器

详细了解 Syslog 提取器字段

定义 Syslog 提取器字段

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

创建代码段说明

编写代码段说明时的提示和最佳实践

创建代码段说明

代码段说明示例

提交代码段说明

管理现有的解析器扩展程序

查看现有的解析器扩展程序

修改解析器扩展程序

删除解析器扩展程序

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

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