使用 Gemini 创建自定义解析器和解析器扩展程序

支持范围：

Google SecOps SIEM

注意： 此功能受 Google Security Operations 服务专用条款的非正式版产品条款约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则和 Google SecOps 服务专用条款。
如果您的环境中未显示此功能，请参阅管理预览版功能或与系统管理员联系。

注意：此功能处于非公开预览版阶段，并非所有区域的所有客户都可以使用。无法在 Google SecOps 平台的“公开预览版管理器”页面中管理非公开预览版功能。

本指南可帮助安全分析师和检测工程师在 Google Security Operations 中使用 AI 解析功能，从头开始构建自定义解析器，或创建可增强现有解析器的解析器扩展程序。借助自然语言提示和供应商文档，您可以将原始日志映射到统一数据模型 (UDM)，而无需编写复杂的解析器语法或正则表达式。

在 AI 自定义解析器和 AI 解析器扩展程序之间进行选择

下表比较了 AI 解析中的“使用 AI 创建解析器”和“使用 AI 编写扩展功能”功能：

特征方面	使用 AI 创建解析器	使用 AI 编写扩展功能
输出	一个完整的独立自定义解析器	在现有解析器上分层的扩展程序
主要用途	新的或不受支持的日志来源，或完整的解析器重写	在正常运行的解析器中添加或修复特定字段
输入	日志类型、提取的原始日志和可选文档链接	日志类型、原始日志示例，以及描述要映射的字段的提示

主要术语

• AI 解析：Google SecOps 中的一套 AI 辅助解析功能，包括 AI 自定义解析器生成（使用 AI 创建解析器）和 AI 解析器扩展程序（使用 AI 编写扩展程序）。
• 统一数据模型 (UDM)：Google SecOps 中用于存储和分析日志数据的标准数据结构。

准备工作

在使用 AI 解析之前，请确认满足以下前提条件：

• 确认已为您的 Google SecOps 实例启用 AI 解析功能。如果您没有看到使用 AI 创建解析器或使用 AI 编写扩展程序选项，请与您的 Google SecOps 代表联系。
• 对于 AI 解析器扩展程序，请验证目标日志类型是否已具有有效的预构建或自定义解析器，并准备一个原始日志示例来测试提取。
• 对于 AI 自定义解析器生成，请在开始之前注入日志源的代表性样本。解析器代理会从您已为所选日志类型提取的日志中学习。如果未找到该日志类型的日志，则无法开始生成。失败的启动尝试不会计入您的配额。
• 对于 AI 自定义解析器生成，请准备 1 到 5 个可公开访问的链接，这些链接指向供应商的日志格式参考文档，例如字段字典、事件架构或日志示例页面（推荐）。全面的文档是影响解析器质量的最大因素。

利用 AI 创建自定义解析器

“使用 AI 创建解析器”功能可从头开始为日志来源构建完整的自定义解析器。您需要选择日志类型，并可选择提供指向供应商日志文档的链接。解析器智能体会对您注入的日志进行采样，研究日志架构，规划原始字段到 UDM 的映射，并使用 JavaScript 编写解析器代码。然后，您可以使用引用原始字段名称和 UDM 字段的简单英语指令来查看结果并对其进行优化。输出准备就绪后，您可以像提交任何其他自定义解析器一样提交该解析器。

借助 AI 自定义解析器生成功能，您可以执行以下操作：

• 添加没有预构建解析器或预构建解析器不符合日志格式的日志源。
• 生成一个完整的解析器，涵盖提取的数据中发现的每种不同的日志格式，而不仅仅是单个样本。
• 通过后续提示优化生成的解析器，而无需自行编写解析器代码。

启动 AI 生成的自定义解析器

1. 在 Google SecOps 中，依次前往 SIEM 设置 > 解析器。
2. 点击添加新解析器。
3. 在创建新的自定义解析器对话框中，选择要解析的日志来源（例如 GCP DNS）。
4. 在您将如何构建解析器？下，选择使用 AI 构建解析器。
5. 点击创建。

添加产品文档并开始生成

注意 ：文档链接是可选的。如果您未添加任何链接，研究阶段会搜索网络以查找供应商的文档，并直接从原始日志中推断架构。这种方法非常适合常见且有详细文档记录的产品。对于小众或内部日志来源，添加链接可提供更好的字段覆盖率。

1. 可选：在解析器代理窗格的添加产品链接字段中，粘贴指向供应商日志文档的链接，然后点击添加。您最多可以添加 5 个链接。文档计数器会显示您已添加的链接数量。
2. 点击生成解析器。

文档链接指南

如需提高生成的解析器中的字段覆盖率，请在选择文档链接时遵循以下准则：

• 仅提供指向供应商文档的公开链接。如果链接是私密的或无法访问，解析器代理会忽略该链接，改为搜索网络，而不会导致生成失败。
• 链接到描述日志字段和事件类型的页面，例如日志架构、字段字典或事件参考。避免使用营销页面或产品概览。
• 选择与您注入的日志格式匹配的页面。例如，如果您注入 JSON 审核日志，请链接到 JSON 审核日志参考文档，而不是 syslog 参考文档。
• 如果供应商在不同的页面上记录了不同的事件类别（例如 DNS 查询、防火墙事件和管理员活动），请为每个事件类别添加一个链接。

跟踪生成进度

自定义解析器开始生成后，状态会更改为正在生成。生成过程包括以下阶段：

阶段	智能体操作	输出已传递到下一阶段
提取原始日志	代理会针对相应日志类型对您注入的日志进行采样。它会对日志进行聚类，以选择一组涵盖每种不同日志格式和事件形状的示例日志。	代表性示例日志
研究文档	代理会阅读您提供的文档链接，如果您未提供链接，则会搜索网络。它会将这些信息与示例日志结合起来，构建日志架构和字段字典。	日志架构和字段字典
创建映射方案	智能体识别日志中的每种事件类型，并规划每个原始日志字段如何映射到相应的 UDM 字段。	每种事件类型的原始字段到 UDM 字段的映射方案
生成解析器代码	智能体将映射方案转换为 JavaScript 解析器代码。它会根据示例日志测试代码并解决错误，直到解析器顺利运行。	可供审核的解析器

注意： 生成过程通常需要 30 到 90 分钟，具体取决于不同日志格式的数量、日志来源的复杂性以及日志架构的大小。您无需让页面保持打开状态。点击关闭，稍后再返回 SIEM 设置 > 解析器。生成完成后，解析器会显示在列表中，并带有 AI 生成标记。

如果因未找到所选日志类型的日志而导致解析器生成失败，请先注入该日志类型的原始日志，然后再重新开始生成。对于任何其他生成失败问题，没有可用的手动分类选项。触发新的生成会话。如果故障仍然存在，请与支持团队联系，提交支持请求。

查看和优化自定义解析器

自定义解析器生成完成后，状态会更改为 AI 生成，并且页面会显示以下窗格：

• 解析器代理：显示使用 AI 优化解析器提示字段，您可以在其中输入后续指令。
• 解析器代码：显示生成的 JavaScript 解析器代码以供审核。生成的代码在提交前为只读。如需修改逻辑，请在使用 AI 优化解析器字段中输入提示。
• 原始日志：显示日志类型的原始日志示例。您可以点击 修改来粘贴您自己的日志行，也可以点击 刷新来加载其他示例。
• 显示 UDM 输出：针对原始日志运行当前解析器代码，并显示生成的 UDM 事件，以便您验证每个映射。

查看生成的输出

在启用解析器之前，请查看示例日志中生成的映射：

1. 加载多个原始日志，包括您要解析的每种事件类型，然后点击每个日志的显示 UDM 输出。
2. 验证解析器是否将原始日志字段映射到适当的 UDM 字段，并准确填充其值（例如，事件元数据、实体字段（如 principal 和 target）以及安全结果字段）。
3. 检查是否有任何重要的原始字段仍未映射。

使用 AI 优化自定义解析器

如果映射不正确或缺失，请在使用 AI 优化解析器字段中输入指令，然后点击确认。解析器代理会更新现有解析器，而不是从头开始，并保留您未提及的所有映射。每次优化都会创建一个新版本的解析器代码，供您查看。

请遵循以下准则，撰写有效的优化提示：

1. 同时说明原始来源字段（或日志中的示例值）和确切的目标 UDM 字段路径。
2. 将相关更改归为一组，避免在单个长提示中混入不相关的修复。
3. 将原始日志中的确切字符串用单引号括起来，例如 'NXDOMAIN' 或 'allow'。
4. 当映射依赖于字段值时，请使用 if ... then ... otherwise ... 结构明确声明条件映射。
5. 指示智能体将没有匹配 UDM 字段的供应商特定属性映射到 additional.fields，并提供清晰的键名称。

下表提供了 GCP DNS 日志的优化提示示例：

目标	提示示例
修正不正确的映射	"Map jsonPayload.sourceIP to principal.ip instead of target.ip."
添加缺失的字段	"Map jsonPayload.vmInstanceName to principal.hostname."
映射嵌套值或重复值	"Map jsonPayload.queryName to network.dns.questions.name and jsonPayload.queryType to network.dns.questions.type."
应用条件逻辑	"If jsonPayload.responseCode is 'NXDOMAIN', set security_result.summary to 'Domain does not exist'. Otherwise, leave it empty."
设置事件类型	"Set metadata.event_type to NETWORK_DNS for all DNS query logs."
映射供应商特定字段	"Map jsonPayload.alias_query_response_code to additional.fields with key 'alias_query_response_code'."
移除映射	"Stop mapping jsonPayload.protocol to network.application_protocol."

注意： 您无法在提交前直接在解析器代码窗格中修改生成的代码。提交并激活解析器后，您可以像编辑任何其他自定义解析器一样手动编辑其代码。

提交并激活自定义解析器

当 UDM 输出准确无误时，点击提交以保存并激活生成的自定义解析器。

如要改为舍弃解析器草稿，请点击舍弃。如需在日后移除已保存的 AI 生成的自定义解析器，请打开该解析器，然后点击删除自定义解析器下的删除。

注意： AI 自定义解析器生成是一项实验性功能。生成的解析器质量可能会有所不同。在生产环境中启用解析器之前，请务必检查每种事件类型的 UDM 输出并验证解析器。

排查 AI 自定义解析器生成问题

下表列出了您在使用 AI 生成自定义解析器时可能会遇到的常见问题以及解决方法：

问题或症状	解决方法
您没有看到使用 AI 创建解析器选项。	您的实例未启用此功能。请与您的 Google SecOps 代表联系。
由于未找到该日志类型的日志，生成失败。	解析器代理需要所选日志类型的已注入原始日志。请先提取该日志类型的原始日志，然后再重新开始生成。
生成因其他原因而失败。	对于失败的生成，没有可用的手动分类选项。再次触发生成。如果故障仍然存在，请与支持团队联系，提交支持请求。
生成过程需要很长时间才能完成。	生成过程通常需要 30 到 90 分钟。具有许多不同格式或大型架构的复杂日志来源需要更长时间。您可以关闭该页面，稍后再返回“SIEM 设置”>“解析器”。
许多字段仍未映射。	添加描述日志字段的文档链接，然后开始新会话，或使用优化提示来映射缺失的字段。
优化提示更改了不相关的映射。	在后续提示中描述更正内容（例如 "Revert the change to principal.ip and map jsonPayload.sourceIP to it again."）。或者，提交并激活解析器，以手动修改代码。
某些日志无法在显示 UDM 输出中解析。	将失败的日志粘贴到原始日志窗格中，然后发送引用日志中未解析部分的优化提示。

使用 AI 创建解析器扩展程序

当 Google SecOps 中的默认日志解析器解析您的日志来源时，可能会忽略客户专属的自定义属性、可选字段或专用遥测数据。使用 AI 解析器扩展程序（使用 AI 编写扩展功能）可让您执行以下操作：

• 从原始日志中提取其他字段，并将其映射到标准 UDM 字段或自定义 additional.fields。
• 应用条件逻辑和值转换，例如将字符串操作映射到 UDM 枚举类型。
• 在多轮对话中以互动方式优化生成的扩展程序，而无需从头开始。

撰写提示的最佳实践

如需获取准确的解析器扩展程序，请遵循以下提示指南：

1. 明确说明要提取原始日志的哪个部分，以及要填充的确切 UDM 字段路径（例如 principal.ip、target.user.email_addresses 或 security_result.action）。
2. 用单引号将非结构化日志中的字面量字符串、定界符或示例值括起来，例如 '198.51.100.0' 或 'allow'。
3. 指示 AI 将没有专用 UDM 字段的专有或供应商特定属性映射到 additional.fields 中，并使用清晰的键名称（例如 additional.fields["application"]）。

生成解析器扩展程序

您可以从 Google SecOps 中的以下任一位置启动解析器扩展工作流：

• 前往 SIEM 设置> 解析器，选择并扩展任何现有日志解析器。
• 在搜索页面上调查日志时，直接从包含未解析字段的事件打开扩展程序创建流程。

如需从解析器页面生成解析器扩展程序，请按以下步骤操作：

1. 在 Google SecOps 中，依次前往 SIEM 设置 > 解析器。
2. 在解析器表中搜索要扩展的日志类型。
3. 在解析器所在的行中，点击 菜单，然后选择扩展解析器 > 创建扩展程序。
4. 在原始日志窗格中，验证示例原始日志，或点击 修改以粘贴要解析的日志示例。
5. 在扩展程序窗格中的扩展程序方法下，选择使用 AI 编写扩展程序。
6. 在提示字段中，输入要提取的字段的简单英文说明。

7. 点击确认。

   系统会生成扩展程序代码并更新 UDM 输出窗格。

优化解析器扩展程序

您可以在多轮对话中迭代构建和优化解析器扩展程序。当您提交后续提示时，AI 会在之前生成的扩展程序的基础上应用您的新指令。除非您明确要求覆盖或移除，否则系统会自动保留之前轮次中的现有映射和条件逻辑。

注意： 离开页面后，会话不会保留。为避免丢失工作进度，请先完成或保存扩展程序，然后再离开。

1. 在提示字段中，输入后续指令以调整生成的代码。
2. 点击确认。
3. 在每个提示之后，预览生成的扩展程序代码，检查 UDM 输出示例，并确认或调整逻辑。

注意： 如果您需要更正上一轮对话中的错误，请用简单的英语说明要更改的内容，例如 "Change the target field for callerIp from target.ip to principal.ip"。

以下示例工作流展示了迭代优化如何通过多轮对话构建解析器扩展程序：

1. 第 1 轮（初始提取）：
   • 用户提示： "Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip."
   • 结果：AI 会生成一个扩展程序，用于映射 principal.ip 和 target.ip。
2. 第 2 轮（加法映射）：
   • 用户提示： "Also map virtual system string 'vsys1' to observer.administrative_domain."
   • 结果：AI 更新了扩展程序，以映射 observer.administrative_domain，同时保留了第 1 轮中的 IP 映射。
3. 第 3 轮（条件式优化）：
   • 用户提示： "In addition, map action string 'allow' to security_result[0].action as ALLOW."
   • 结果：AI 会在之前所有提取内容的基础上，纳入根据条件触发的操作枚举映射。

验证解析器扩展程序

1. 点击验证。
2. 流程完成后，查看验证指标。

访问参考信息

请参考以下示例，为解析器扩展程序撰写准确的提示。

结构化日志提示

对于结构化日志（数据按命名的键、属性或 XML 标记进行整理），请在提示中指定字段名称或路径。

结构化日志示例 - JSON 格式

{
  "insertId": "u0mlpdesys",
  "logName": "projects/sample-project-id/logs/cloudaudit.googleapis.com%2Fdata_access",
  "protoPayload": {
    "authenticationInfo": {
      "principalEmail": "[e-mail]"
    },
    "methodName": "GenerateAccessToken",
    "requestMetadata": {
      "callerIp": "203.0.113.195",
      "callerSuppliedUserAgent": "google-cloud-sdk gcloud/392.0.0"
    },
    "resourceName": "projects/-/serviceAccounts/110649196922301550006",
    "serviceName": "iamcredentials.googleapis.com"
  }
}

结构化日志的提示示例

提示指令	来源字段或键	目标 UDM 字段
"Map principalEmail to principal.user.email_addresses."	principalEmail	principal.user.email_addresses
"Extract callerIp to principal.ip and methodName to metadata.product_event_type."	callerIp，methodName	principal.ip、metadata.product_event_type
"Map resourceName to target.resource.name and serviceName to target.application."	resourceName、serviceName	target.resource.name，target.application
"From XML tags, map /Event/System/Hostname to principal.hostname."	/Event/System/Hostname	principal.hostname

非结构化日志提示

对于非结构化日志，请直接从示例日志、位置引用或描述性标签中指定字面量值。

非结构化 syslog 消息示例

<14>Nov  9 18:52:45 198.51.100.1 1,2021/11/09 18:52:45,007051000184334,TRAFFIC,start,2561,2021/11/09 18:52:45,198.51.100.0,198.51.100.1,0.0.0.0,0.0.0.0,any allow,,,ping,vsys1,LAN,LAN,ethernet1/2,ethernet1/2,LFPpan,2021/11/09 18:52:45,9729,6,0,0,2048,0,0x100000,icmp,allow,444,444,0,6

非结构化日志的提示示例

提示指令	字面量值或说明示例	目标 UDM 字段
"Extract source IP '198.51.100.0' to principal.ip and destination IP '198.51.100.1' to target.ip."	'198.51.100.0'，'198.51.100.1'	principal.ip，target.ip
"Extract the application string 'ping' from the log and map it to additional.fields['application']."	'ping'	additional.fields["application"]
"Map rule name 'any allow' to security_result.rule_id."	'any allow'	security_result[0].rule_id
"Extract sent bytes and received bytes into network.sent_bytes and network.received_bytes."	日志中的数字字节计数器	network.sent_bytes，network.received_bytes

条件逻辑提示

描述条件逻辑，以将原始日志值标准化为特定 UDM 枚举。

• 枚举标准化： "If the firewall action in the log is 'allow', set security_result.action to ALLOW; otherwise set security_result.action to BLOCK."
• 条件字段映射： "If the protocol is 'icmp', map the ICMP type and code into network.icmp.type and network.icmp.code."
• 状态映射： "When the log status contains 'success' or '0', set security_result.severity to INFO; if it contains 'error', set it to ERROR."

用量限额

为了保持最佳性能和资源可用性，AI 解析功能会强制执行以下默认用量配额：

• 在 24 小时滚动时间范围内，每个实例最多可以启动 10 个 AI 自定义解析器生成或 AI 解析器扩展会话。对于自定义解析器，每次点击 Generate Parser（生成解析器）以生成新解析器时，都会启动一个会话。
• 每个会话都遵循以下互动限制：
  • 对于 AI 自定义解析器生成，每个会话总共最多支持 6 轮对话，其中包括初始生成以及最多 5 个优化提示。
  • 对于 AI 解析器扩展程序，每个会话总共最多支持 5 条消息，其中包括您的初始提示和后续优化轮次。

如果您达到某个会话的轮次或消息上限，可以提交或保存当前工作，也可以开始新会话（受每日会话配额限制）。对于自定义解析器，在提交并激活解析器后，您可以像任何其他自定义解析器一样手动修改其代码。

后续步骤

• 如需详细了解如何创建和管理自定义解析器，请参阅配置自定义解析器。
• 如需详细了解其他解析器扩展方法，请参阅开发解析器扩展。
• 如需查看示例扩展程序代码段和场景，请参阅解析器扩展程序示例。
• 如需简要了解如何将原始日志解析为 UDM，请参阅日志解析概览。

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