在 Microsoft Sentinel playbook 中使用触发器和操作

项目
03/04/2024

本文档介绍 playbook 可以用来与 Microsoft Sentinel 和工作区表中的信息进行交互的逻辑应用 Microsoft Sentinel 连接器中的触发器和操作的类型。本文档进一步说明了如何访问可能需要的特定类型的 Microsoft Sentinel 信息。

本文档和向 Microsoft Sentinel 验证 playbook 的指南一起与另一 playbook 文档配套 - 教程：在 Microsoft Sentinel 中结合自动化规则使用 playbook。这三个文档将相互引用。

有关 playbook 的简介，请参阅在 Microsoft Sentinel 中使用 playbook 实现威胁响应自动化。

有关 Microsoft Sentinel 连接器的完整规范，请参阅逻辑应用连接器文档。

所需的权限

角色\连接器组件	触发器	“获取”操作	更新事件，添加注释
Microsoft Sentinel 读取者	✓	✓	✗
Microsoft Sentinel 响应者/参与者	✓	✓	✓

详细了解 Microsoft Sentinel 中的权限。

Microsoft Sentinel 触发器摘要

尽管可以通过多种方式使用 Microsoft Sentinel 连接器，但是可以将连接器的组件分为三个流，每个流由不同的 Microsoft Sentinel 事件触发：

触发器（逻辑应用设计器中的全名）	何时使用	已知限制
Microsoft Sentinel 事件(预览版)	建议用于大多数事件自动化情况。 playbook 接收事件对象，包括实体和警报。使用此触发器允许将 playbook 附加到“自动化规则”，以便在 Microsoft Sentinel 中创建和更新事件时，可以触发 playbook，并且自动化规则的优点全部都可以应用到事件。	使用此触发器的 playbook 不支持警报分组，这意味着它们将仅接收每个事件发送的第一个警报。更新：从 2023 年 2 月起，此触发器支持警报分组。
Microsoft Sentinel 警报(预览版)	建议用于需要在 Microsoft Sentinel 门户上针对警报手动运行的 playbook，或用于不生成警报事件的“计划”分析规则。	此触发器不能用于自动响应由“Microsoft 安全”分析规则生成的警报。 “自动化规则”无法调用使用此触发器的 playbook。
Microsoft Sentinel 实体(预览版)	用于需要对调查或威胁搜寻上下文中的特定实体手动运行的 playbook。	“自动化规则”无法调用使用此触发器的 playbook。

这些流使用的架构并不相同。建议的做法是使用适用于大多数情况的“Microsoft Sentinel 事件触发器”流。

事件动态字段

从 Microsoft Sentinel 事件接收的“事件”对象包括以下动态字段：

事件属性（显示为“Incident: 字段名称”）
警报（数组）
- 警报属性（显示为“Alert: 字段名称”）
  
  选择警报属性（如“Alert: property name>”）时，将自动生成一个“for each”循环，因为事件可能包含多个警报。
实体（所有警报实体的数组）
工作区信息字段（适用于在其中创建事件的 Sentinel 工作区）
- 订阅 ID
- 工作区名称
- 工作区 ID
- 资源组名称

Microsoft Sentinel 操作摘要

组件	何时使用
“警报 - 获取事件”	在以警报触发器开头的 playbook 中。可用于获取事件属性，或检索“事件 ARM ID”以与“更新事件”或“向事件添加注释”操作一起使用。
获取事件	从外部源或使用非 Sentinel 触发器触发 playbook 时。使用“事件 ARM ID”标识。检索事件属性和注释。
更新事件	更改事件的“状态”（例如，关闭事件时），分配“所有者”，添加或删除标记，或更改其“严重性”、“标题”或“说明”。
“向事件添加注释”	用从外部源收集的信息扩充事件；审核 playbook 对实体执行的操作；提供对事件调查有用的其他信息。
实体 - 获取 <entity type>	在处理创建 playbook 时已知的特定实体类型（“IP”、“帐户”、“主机”、“URL”或“FileHash”）的 playbook 中，并且需要能够对其进行分析和处理其唯一字段。

处理事件 - 用法示例

提示

操作“更新事件”和操作“向事件添加注释”需要“事件 ARM ID”。

事先使用“警报-获取事件”操作来获取“事件 ARM ID”。

更新事件

Playbook 由 Microsoft Sentinel 事件触发
Playbook 由 Microsoft Sentinel 警报触发

使用事件信息

用于通过邮件发送事件详细信息的基本 playbook：

Playbook 由 Microsoft Sentinel 事件触发
Playbook 由 Microsoft Sentinel 警报触发

向事件添加注释

Playbook 由 Microsoft Sentinel 事件触发
Playbook 由 Microsoft Sentinel 警报触发

禁用用户

Playbook 由 Microsoft Sentinel 实体触发

没有事件 ID 的实体 playbook

使用实体触发器创建的 playbook 通常使用“事件 ARM ID”字段（例如，为了在对实体执行操作后更新事件）。

如果在与事件无关的上下文（例如，在搜寻威胁时）中触发此类 playbook，则没有任何事件的 ID 可以填充此字段。在这种情况下，将使用 null 值填充该字段。

因此，playbook 可能无法运行到完成。 为防止此失败，建议创建一个条件，在对事件 ID 字段执行任何操作之前检查该字段中的值，如果字段具有 null 值（即，如果 playbook 未从事件中运行），则指定一组不同的操作。

在引用“事件 ARM ID”字段的第一个操作之前，添加一个“条件”类型的步骤。
选择“选择值”字段，进入“添加动态内容”对话框。
选择“表达式”选项卡和“length(collection)”函数。
选择“动态内容”选项卡和“事件 ARM ID”字段。
验证生成的表达式为 length(triggerBody()?['IncidentArmID'])，然后选择“确定”。
将条件中的“运算符”和“值”设置为“大于”和“0”。
在“True”帧中，添加从事件上下文运行 playbook 时要执行的操作。

在“False”帧中，添加从非事件上下文运行 playbook 时要执行的操作。

处理特定实体类型

“实体”动态字段是 JSON 对象的数组，其中每个对象都表示一个实体。每个实体类型都有自己的架构，具体取决于它的唯一属性。

“实体 - 获取 <entity type>”操作可执行以下操作：

按请求的类型筛选实体数组。
分析此类型的特定字段，使其可以在进一步操作中用作动态字段。

输入是“实体”动态字段。

响应是实体的数组，其中特殊属性经过分析，并可直接在“For each”循环中使用。

当前支持的实体类型包括：

对于其他实体类型，可以使用逻辑应用的内置操作来实现类似的功能：

使用“筛选数组”，按请求的类型筛选实体数组。
使用“分析 JSON”，分析此类型的特定字段，使其可以在进一步操作中用作动态字段。

处理自定义详细信息

“事件触发器”中提供的“警报自定义详细信息”动态字段是 JSON 对象的数组，其中每个对象表示一个警报的自定义详细信息。应该知道，自定义详细信息是键值对，可用于从警报中的事件呈现信息，以便可以作为事件的一部分来表示、跟踪和分析。

由于警报中的此字段是可自定义的，因此其架构取决于要呈现的事件的类型。必须提供此事件实例的数据，以生成用于确定如何分析自定义详细信息字段的架构。

请参阅以下示例：

Custom details defined in analytics rule.

在这些键值对中，键（左侧列）表示创建的自定义字段，值（右侧列）表示填充自定义字段的事件数据中的字段。

可以提供以下 JSON 代码来生成架构。该代码将键名称显示为数组，将值（显示为实际值，而不是包含值的列）显示为数组中的项。

{ "FirstCustomField": [ "1", "2" ], "SecondCustomField": [ "a", "b" ] }

使用“分析 JSON”内置操作添加新步骤。可以在“搜索”字段中输入“parse json”来查找。
在事件触发器下的“动态内容”列表中查找并选择“警报自定义详细信息”。

这将创建“For each”循环，因为事件包含警报数组。
单击“使用示例有效负载生成架构”链接。
提供示例有效负载。可以通过在日志分析（“日志”边栏选项卡）中查找此警报的另一个实例并复制自定义详细信息对象（在“扩展属性”下），来查找示例有效负载。在下面的屏幕截图中，我们使用了上面所示的 JSON 代码。
自定义字段是可供使用的“数组”类型的动态字段。可以在此处查看数组及其项，包括架构中和显示在"动态内容"下的列表中，如上所述。