使用解析器扩展

Google Security Operations 提供了多种方法来定义如何解析原始原始日志中的数据并将其标准化为统一数据模型 (UDM) 记录。

  • 默认解析器:由 Google Security Operations 管理的预构建数据映射指令,用于将原始原始日志数据映射到 UDM 字段。
  • 自定义解析器:由客户创建和管理的自定义数据映射指令,用于满足客户的特定数据解析需求。
  • 解析器扩展程序:额外的数据映射指令,用于扩展默认或自定义解析器以映射原始原始日志中的其他字段。这不会完全替换默认或自定义解析器,但会扩展默认或自定义解析器中的现有映射指令。

本文档介绍了如何使用解析器扩展。

准备工作

以下文档介绍了在使用解析器扩展时需要了解的先决概念:

解析器扩展简介

借助解析器扩展,您可以在默认或自定义解析器中定义的映射指令之外创建其他映射指令,以满足独特的用例。此功能旨在扩展现有的默认或自定义解析器。解析器扩展程序不会替换默认或自定义解析器。您无法使用解析器扩展创建新的解析器。

解析器扩展程序会读取原始原始日志,并将提取的值插入 UDM 记录中的特定字段。UDM 记录包含由默认或自定义解析器和解析器扩展程序设置的数据。

解析器扩展程序中的数据映射指令优先于默认或自定义解析器中的数据映射指令。如果映射指令发生冲突,解析器扩展程序将覆盖默认或自定义解析器设置的值。例如,如果默认解析器将原始日志字段映射到 event.metadata.description UDM 字段,而解析器扩展程序将不同的原始日志字段映射到同一 UDM 字段,则解析器扩展程序将覆盖默认解析器设置的值。重复字段属于例外情况。您可以将解析器扩展程序配置为在将数据写入重复字段时附加值。

您需要为每种日志类型创建一个解析器扩展程序。每种日志类型都由唯一的提取标签进行标识。如需查看日志类型的列表,请参阅支持的默认解析器

如需创建解析器扩展程序,Google Security Operations 必须能够使用默认或自定义解析器注入原始原始日志并进行标准化。解析器扩展程序会从原始原始日志中提取其他数据,然后将其合并到 UDM 记录中。

解析器扩展支持以下类型的映射指令:

  • 代码段类型:您可以编写类似于默认和自定义解析器的解析器代码。 原始原始日志可以采用相应日志类型支持的数据格式
  • 数据字段类型:您可以在应用界面中指定出发地和目的地字段。原始原始日志必须采用以下任一格式:
    • 原生 JSON、原生 XML 或 CSV。
    • Syslog 头文件以及原生 JSON、原生 XML 或 CSV。 您可以在支持的默认解析器中为部分日志类型创建数据字段类型映射说明。查找格式为 JSONXMLCSVSYSLOG + JSONSYSLOG + XMLSYSLOG + CSV 的变量。

在创建解析器扩展程序时,请注意以下事项:

  • 数据可映射到支持标准数据类型和重复值的任何 UDM 字段。
  • 您无法将数据映射到以下 UDM 字段:
    • event.idm.read_only_udm.additional
    • event.idm.graph.entity.additional
  • 在创建数据映射指令之前,请确保您的 Google Security Operations 实例在过去 30 天内提取了相应日志类型的原始原始日志,并且这些原始日志包含您计划在前提条件条件中定义的字段。这些原始原始日志用于验证数据映射指令。
  • 解析器扩展程序投入使用后,便会开始解析传入的数据。您无法追溯解析原始日志数据。

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

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

  • DRAFT:新创建的解析器扩展程序,尚未提交。
  • VALIDATING:Google Security Operations 会根据现有原始日志验证映射指令,以确保解析字段时正确无误。
  • LIVE:解析器扩展程序通过了验证,现已正式发布。它从传入的原始日志中提取数据并将其转换为 UDM 记录。
  • FAILED:解析器扩展验证失败。

打开“Parser Extensions”页面

执行以下某个部分中的步骤以访问解析器扩展程序页面。

从导航栏开始

  1. 在导航栏中,依次选择 Settings(设置)、SIEM Settings(SIEM 设置)和 Parsers(解析器)。
  2. 确定要在解析器表中扩展的日志类型。
  3. 转到该行,然后点击 菜单
  4. 点击创建扩展程序
  1. 使用原始日志搜索来搜索与将被解析的记录类似的记录。
  2. 事件 > 时间轴面板中选择一个事件。
  3. 展开事件数据面板。
  4. 点击 Manage Parser 按钮。
  5. Manage Parser 对话框中,选择 Create Extension,然后点击 NextParser Extensions 页面会在修改模式下打开。您可以开始定义解析器扩展。

创建新的解析器扩展程序

本部分介绍如何在打开“解析器扩展程序”页面后创建解析器扩展程序。解析器扩展程序页面上的可用字段将有所不同,具体取决于原始日志的结构。

  1. 查看 Raw Log 面板中的原始符号示例,确认它代表了解析器扩展程序将处理的日志。创建解析器扩展程序时,请使用原始日志示例作为参考。

    • 如果您从原始日志搜索导航到 Parser Extensions 页面,该面板会显示您在搜索结果中选择的原始原始日志。

    • 如果您导航到导航栏中的解析器扩展程序页面,则会显示该日志类型的示例原始日志。

  2. 选择 Extension Method(扩展方法)。从下列选项中选择一项:

    • 映射数据字段:创建数据字段映射。使用应用字段定义原始原始日志字段和目标 UDM 字段。

    • 编写代码段:为所有支持的日志格式创建代码段。代码段使用的解析器语法与默认和自定义解析器相同。如需详细了解解析器语法,请参阅解析器语法

继续完成所选扩展方法的以下某个子部分。

创建数据字段映射说明

当传入的原始日志采用 JSON、XML、CSV、Syslog 标头加 JSON、Syslog 标头加 XML 或 Syslog 标头加 CSV 格式时,创建数据字段映射指令。在数据映射指令中定义原始字段名称和目标 UDM 字段的路径。

  1. 重复字段选择器中,指定解析器扩展程序如何将值保存到支持值数组的字段。

    • 附加值:该值将附加到存储在该字段中的现有值集。
    • 替换值:使用新值替换之前存储的所有值。

    某些 UDM 字段(例如 principal.ipentity.asset.hostname)用于存储值数组。这些重复字段在统一数据模型字段列表中由标签 repeated 标识。如需了解详情,请参阅重复字段选择器

  2. 如果出现 SyslogTarget 字段,则表示 Google Security Operations 检测到原始日志包含 Syslog 标头。

    如果 Google Security Operations 发现示例原始日志不是原生 JSON、原生 XML 或 CSV 并且具有 Syslog 标头,则会显示 SyslogTarget 字段。使用以下字段定义 Grok 和正则表达式模式,这些模式会预处理 Syslog 标头并提取日志的结构化部分。日志的结构化部分可以使用数据字段进行映射。

    • Syslog 字段:使用 Grok 和正则表达式指定提取模式,用于标识 Syslog 标头和原始日志消息。
    • Target 字段:在存储日志结构化部分的提取模式中指定变量名称。

    如需了解如何使用 Grok 和正则表达式定义提取模式,请参阅定义 Syslog 提取器字段

    下图举例说明了如何将提取模式和变量名称分别添加到 SyslogTarget 字段。

    Syslog 提取器字段

    SyslogTarget 字段都是必填字段,它们可以协同工作,将 Syslog 标头与日志的结构化部分分隔开来。

  3. Syslog目标字段中输入值后,点击验证按钮。 验证流程会检查语法和解析错误,然后返回以下任何一项:

    • 成功:数据映射字段显示。定义解析器扩展的其余部分。
    • 失败:系统会显示错误消息。请先更正错误情况,然后再继续。
  4. (可选)定义一个前提条件指令。

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

    填写以下字段:

    • 前提条件字段:如果日志数据格式为 JSON 或 XML,则输入字段的完整路径;如果数据格式为 CSV,则输入列位置。
    • 前提条件运算符:选择 EQUALSNOT EQUALS
    • Precondition Value(前提条件值):输入必须与 Precondition Field 中的数据匹配的值。
  5. 定义数据映射指令:

    • 原始数据字段:如果日志数据格式为 JSON 或 XML,则输入字段的完整路径;如果数据格式为 CSV,则输入列位置。
    • 目标字段:输入用于存储值的完全限定 UDM 字段名称,例如 udm.metadata.collected_timestamp.seconds
  6. 点击提交,保存映射说明。

  7. Google Security Operations 会验证映射说明。

    • 如果验证流程成功,则状态将更改为 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"}
    

如需查看解析器扩展程序中所有可能字段的列表,请参阅数据映射说明中的字段

数据映射说明中的字段

本部分介绍了可在解析器扩展程序中设置的所有字段。

字段名称 说明
Syslog 一种用户定义的模式,用于预处理 Syslog 标头并将其与原始日志的结构化部分分开。
目标 Syslog 字段中的变量名称,用于存储日志的结构化部分。
前提条件字段 原始日志中包含要比较的值的字段标识符。在前提条件指令中使用。
前提条件运算符 选择 EQUALSNOT EQUALS。在前提条件指令中使用。
前提条件值 将与原始日志中的前提条件字段进行比较的静态值。在前提条件指令中使用。
原始数据字段

在映射说明中使用。

如果数据格式为 JSON,请定义字段的路径,例如:jsonPayload.connection.dest_ip

如果数据格式为 XML,请定义字段的完整路径,例如:/Event/Reason-Code

如果数据格式为 CSV,请定义该列的索引位置。 索引位置从 1 开始。

目标字段

在映射说明中使用。

定义将在其中存储数据的 UDM 字段的完整路径。例如:

udm.network.dhcp.opcode


graph.entity.asset.hostname

创建代码段映射说明

代码段使用类似 Logstash 的语法定义如何提取和转换原始原始日志中的值,并将其分配给 UDM 记录。代码段使用的语法和指令部分与默认或自定义解析器相同。代码段中的各部分如下所示:

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

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

下面是一个原始日志示例:

{
    "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 the data from the original 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"
                    }
                }
            }
        }
    }
}
  1. 点击提交,保存映射说明。

  2. Google Security Operations 会验证映射说明。

    • 如果验证流程成功,则状态将更改为 Live,并且映射指令开始处理传入的日志数据。
    • 如果验证过程失败,状态将更改为“失败”,并且“原始日志”字段中会显示错误。

查看现有解析器扩展程序

  1. 在导航栏中,依次选择 Settings(设置)、SIEM Settings(SIEM 设置)和 Parsers(解析器)。
  2. 在“解析器”列表中,使用解析器扩展程序标识日志类型。此 ID 由名称旁边的 EXTENSION 文本标识。
  3. 转到该行,然后点击 菜单
  4. 点击查看扩展程序
  5. 此时将显示 View Custom/Prebuilt Parser > Extension Tab,其中包含有关该解析器扩展的详细信息。默认情况下,摘要面板会显示 LIVE 解析器扩展程序

修改解析器扩展程序

  1. 打开 View Custom/Prebuilt Parser > “Extension”标签页。 请参阅查看现有解析器扩展程序,了解如何打开该网页。
  2. 点击修改附加信息按钮。随即会出现 Parser Extensions 页面。
  3. 修改 paser 扩展程序。
    • 要取消修改并舍弃更改,请点击舍弃草稿
  4. 修改完解析器扩展程序后,点击 Submit
  5. 如果您提交了更改,系统会运行验证流程来验证新配置。

删除解析器扩展程序

  1. 打开 View Custom/Prebuilt Parser > “Extension”标签页。 如需了解如何打开该页面,请参阅查看现有解析器扩展程序

  2. 点击修改附加信息按钮。随即会出现 Parser Extensions 页面。

  3. 点击删除扩展程序按钮。

在修改解析器扩展程序时,您可以随时将其删除。点击下列选项之一:

  • 舍弃草稿
  • 删除失败的扩展程序

详细了解重复字段选择器

某些 UDM 字段会存储值数组,例如 principal.ipEntity.asset.hostname。如果您创建解析器扩展以将数据存储在重复字段中,则可以通过此选项控制是将值附加到数组,还是替换默认解析器设置的所有现有值。重复字段由统一数据模型字段列表中重复的标签标识。

如果选择了附加值,则解析器扩展程序会将提取的值附加到 UDM 字段中现有值的数组。如果选择了 Replace Values,则解析器扩展程序会将 UDM 字段中的现有值数组替换为提取值。重复字段选择器不会影响不重复的字段中存储数据的方式。

仅当重复字段位于层次结构的最低级别时,解析器扩展才能将数据映射到重复字段。例如,支持将值映射到 udm.principal.ip,因为重复的 ip 字段位于层次结构的最低级别,而 principal 不是重复字段。不支持将值映射到 udm.intermediary.hostname,因为 intermediary 是重复字段,并且不在层次结构的最低级别。

下表提供了重复字段配置如何影响生成的 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 提取器字段

SyslogTarget 字段中的值共同定义解析器扩展程序如何将 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"}

下图显示了填写好的 SyslogTarget 字段:

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.

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

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

下表汇总了 Google Security Operations 中的新角色。

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