使用解析器扩展程序
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。
您可以为日志的子集创建数据字段类型映射说明
支持的默认解析器中的类型。
查找格式为
JSON
、XML
、CSV
、SYSLOG + JSON
、SYSLOG + XML
和SYSLOG + CSV
的变量。
在创建解析器扩展程序时,请注意以下事项:
- 数据可映射到任何支持 标准数据类型 和重复值。
- 您无法将数据映射到以下 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”页面
执行以下某个部分中的步骤以访问解析器扩展程序页面。
从导航栏开始
- 在导航栏中,选择 Settings,SIEM Settings,然后选择 Parsers。
- 确定要在解析器表中扩展的日志类型。
- 转到该行,然后点击 菜单。
- 点击创建扩展程序。
从原始日志搜索开始
- 使用原始日志搜索进行搜索 用于与将被解析的记录类似的记录。
- 从事件 >时间轴面板上。
- 展开事件数据面板。
- 点击 Manage Parser 按钮。
- 在 Manage Parser 对话框中,选择 Create Extension,然后点击 Next。 Parser Extensions 页面会在修改模式下打开。您可以开始定义 解析器扩展程序。
创建新的解析器扩展程序
本部分将介绍如何创建解析器扩展程序, 打开“解析器扩展程序”页面。 解析器扩展页面上的可用字段将有所不同,具体取决于 原始日志的结构。
请查看 Raw Log 面板中的原始登录示例, 代表解析器扩展程序将要处理的日志。使用示例原始日志 作为参考
如果您是从“原始日志搜索”页面转到 Parser Extensions 页面,则该面板会显示您在搜索结果中选择的原始日志。
如果您在导航栏中前往了解析器扩展页面,系统会显示该日志类型的示例原始日志。
选择 Extension Method(扩展方法)。从下列选项中选择一项:
继续完成所选扩展方法的以下某个子部分。
创建数据字段映射说明
在收到原始日志时创建数据字段映射指令 采用 JSON、XML、CSV、Syslog 标头加 JSON、Syslog 标头加 XML 格式 或 Syslog 标头加 CSV 格式。定义原始字段的路径 名称和目标 UDM 字段。
在重复字段选择器中,指定解析器扩展程序如何将值保存到支持值数组的字段。
- 附加值:该值将附加到所存储的一组现有值。
- 替换值:使用新值替换之前存储的所有值。
某些 UDM 字段,例如 principal.ip 和 entity.asset.hostname, 存储值数组。这些重复字段由
repeated
统一数据模型字段列表。 如需了解详情,请参阅重复字段选择器。如果出现 Syslog 和 Target 字段,则表示 Google Security Operations 检测到原始日志包含 Syslog 标头。
如果 Google Security Operations 确定示例原始日志不是原生日志 JSON、原生 XML 或 CSV 文件且具有 Syslog 标头,则会显示 Syslog 和目标字段。 使用以下字段定义 Grok 和正则表达式模式,以预处理 Syslog 标头并提取日志的结构化部分。您可以使用数据字段映射日志的结构化部分。
- Syslog 字段:使用 Grok 和正则表达式指定提取模式, 用于标识 Syslog 标头和原始日志消息。
- 目标字段:在用于存储日志结构化部分的提取模式中指定变量名称。
有关如何使用 Grok 和常规命令定义提取模式的信息 表达式,请参阅定义 Syslog 提取器字段。
下图举例说明了如何添加提取模式和变量名称 Syslog 和 Target 字段分别进行修改。
Syslog 和 Target 字段都是必填字段,它们协同工作 Syslog 标头与日志的结构化部分分隔开来。
在 Syslog 和目标字段中输入值后,点击验证按钮。 验证流程会检查语法和解析错误,然后返回 以下任意一项:
- 成功:数据映射字段显示。定义解析器扩展的其余部分。
- 失败:系统会显示错误消息。请先更正错误情况,然后再继续。
(可选)定义前提条件指令。
前提条件指令仅标识一部分原始原始日志, 解析器扩展通过将静态值与原始 日志。如果传入的原始日志满足前提条件(即值匹配),则解析器扩展程序会应用映射指令。如果值不匹配,则解析器扩展不会应用该映射指令。
填写以下字段:
- 前提条件字段:如果日志数据格式为 JSON 或 XML,请输入字段的完整路径;如果数据格式为 CSV,请输入列位置。
- 前提条件运算符:选择
EQUALS
或NOT EQUALS
。 - 前提条件值:输入必须与前提条件字段中的数据匹配的值。
定义数据映射指令:
- 原始数据字段:如果日志 数据格式为 JSON 或 XML,或者为列位置(如果数据 格式为 CSV。
- 目标字段:输入完全限定的 UDM 字段名称,其中的值
将被存储,例如
udm.metadata.collected_timestamp.seconds
。
点击提交,保存映射说明。
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 字段中的变量名称,用于存储日志的结构化部分。 |
前提条件字段 | 原始日志中包含要比较的值的字段标识符。已使用 。 |
前提条件运算符 | 选择 EQUALS 或 NOT EQUALS 。已使用
。 |
前提条件值 | 将与原始日志中的前提条件字段进行比较的静态值。 在前提条件指令中使用。 |
原始数据字段 | 在映射说明中使用。 如果数据格式为 JSON,请定义字段的路径,例如:
如果数据格式为 XML,请定义字段的完整路径,例如:
如果数据格式为 CSV,请定义该列的索引位置。 索引位置从 1 开始。 |
目标字段 | 在映射说明中使用。 定义将存储数据的 UDM 字段的完整路径。例如:
|
创建代码段映射说明
代码段使用类似 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"
}
}
}
}
}
}
点击提交以保存映射说明。
Google Security Operations 会验证映射说明。
- 如果验证过程成功,状态将变为 Live,并且映射 指令开始处理传入的日志数据。
- 如果验证过程失败,状态会更改为“失败”,并显示错误 显示在原始日志字段中。
查看现有的解析器扩展程序
- 在导航栏中,选择 Settings,SIEM Settings,然后选择 Parsers。
- 在“解析器”列表中,使用解析器扩展程序标识日志类型。识别
文字
EXTENSION
。 - 前往相应行,然后点击 Menu(菜单)。
- 点击查看扩展程序。
- View Custom/Prebuilt 解析器 >系统会显示扩展程序标签页,其中包含有关解析器扩展程序的详细信息。
摘要面板默认会显示
LIVE
解析器扩展程序。如果有
修改解析器扩展程序
- 依次打开 View Custom/Prebuilt Parser(查看自定义/预构建解析器)> Extension tab(扩展程序标签页)。 如需了解如何打开该页面,请参阅查看现有解析器扩展程序。
- 点击修改附加信息按钮。随即会出现 Parser Extensions 页面。
- 修改 paser 扩展程序。
- 要取消修改并舍弃更改,请点击舍弃草稿。
- 修改完解析器扩展程序后,点击 Submit。
如果您提交了更改,系统会运行验证流程来验证新配置。
删除解析器扩展程序
依次打开 View Custom/Prebuilt Parser(查看自定义/预构建解析器)> Extension tab(扩展程序标签页)。 有关说明,请参阅查看现有的解析器扩展程序 如何打开这个页面。
点击修改附加信息按钮。随即会出现 Parser Extensions 页面。
点击删除扩展程序按钮。
在修改解析器扩展程序时,您可以随时将其删除。点击下列选项之一:
- 舍弃草稿
- 删除失败的扩展程序
详细了解重复字段选择器
某些 UDM 字段会存储值数组,例如 principal.ip 和 Entity.asset.hostname。如果您 创建解析器扩展程序以将数据存储在重复字段中,此选项 您可以控制是将值附加到数组,还是 会替换默认解析器设置的所有现有值。重复字段已被标识 (统一数据模型字段列表中重复列出的标签)。
如果选择了附加值,解析器扩展程序会将 提取值添加到 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:
|
在应用扩展程序之前由预构建解析器生成的事件。
metadata:{event_timestamp:{} ... principal:{ip:"1.1.1.1"}}}
应用扩展后输出。
|
替换值 | {"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 输出
|
详细了解 Syslog 提取器字段
Syslog 提取器字段可让您将 Syslog 标头与结构化日志分离开来 方法是定义 Grok、正则表达式和正则表达式模式中的命名标记,以存储输出。
定义 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 提取模式、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 中的新角色。
功能 | 操作 | 说明 |
---|---|---|
解析器 | 删除 | 删除解析器扩展。 |
解析器 | 修改 | 创建和修改解析器扩展程序。 |
解析器 | 查看 | 查看解析器扩展。 |