« 检测 API 获取规则 »
Elastic 文档 ›Elastic 安全解决方案 [8.16] ›Elastic 安全 API ›检测 API

创建规则

编辑

创建规则

编辑

新的 API 参考

有关最新的 API 详细信息，请参阅 检测 API。

当与 API 密钥 身份验证一起使用时，用户的密钥将分配给受影响的规则。如果用户的密钥被删除或用户变得不活跃，则规则将停止运行。

如果用于授权的 API 密钥的权限与创建或最近更新规则的密钥的权限不同，则规则的行为可能会发生变化。

创建新的检测规则。

您可以创建以下类型的规则

  • 自定义查询：搜索定义的索引，并在文档与规则的 KQL 查询匹配时创建警报。
  • 事件关联：搜索定义的索引，并在结果与 事件查询语言 (EQL) 查询匹配时创建警报。

  • 阈值：搜索定义的索引，并在指定字段的值在单个执行期间达到阈值次数时创建警报。当有多个值满足阈值时，将为每个值生成一个警报。

    例如，如果阈值 field 是 source.ip 并且其 value 是 10，则将为在规则的搜索结果中至少出现 10 次的每个源 IP 地址生成警报。如果您感兴趣，请参阅 术语聚合 以获取更多信息。

  • 指标匹配：当字段与指定的 Elasticsearch 索引 中定义的值匹配时创建警报。例如，您可以为 IP 地址创建一个索引，并使用此索引在事件的 destination.ip 等于索引中的值时创建警报。索引的字段映射应符合 ECS。
  • 新术语：在指定的时间范围内，针对源文档中检测到的每个新术语生成警报。
  • ES|QL：使用 Elasticsearch 查询语言 (ES|QL) 查找事件并聚合搜索结果。
  • 机器学习规则：当机器学习作业发现高于定义阈值的异常时创建警报（请参阅 异常检测）。

要创建机器学习规则，您必须拥有 相应的许可证 或使用 云部署。此外，为了使机器学习规则能够正常运行，关联的机器学习作业必须正在运行。

要检索创建机器学习作业所需的机器学习作业 ID，请调用 Elasticsearch 获取作业 API。在 groups 字段中包含 siem 的机器学习作业可用于创建规则

...
"job_id": "linux_anomalous_network_activity_ecs",
"job_type": "anomaly_detector",
"job_version": "7.7.0",
"groups": [
  "auditbeat",
  "process",
  "siem"
],
...

此外，您还可以设置规则创建警报时的通知。这些通知使用 Kibana 的 警报和操作框架。每种操作类型都需要一个连接器。连接器存储通过外部系统发送通知所需的信息。以下连接器类型受规则通知支持

  • Slack
  • 电子邮件
  • PagerDuty
  • Webhook
  • Microsoft Teams
  • IBM Resilient
  • Jira
  • ServiceNow ITSM

有关 PagerDuty 字段的更多信息，请参阅 发送 v2 事件。

要检索配置规则通知所需的连接器 ID，请使用请求有效负载中 "type": "action" 调用 Kibana 的 查找对象 API。

有关 Kibana 操作和警报以及其他 API 调用的详细信息，请参阅

请求 URL

编辑

POST <kibana 主机>:<端口>/api/detection_engine/rules

请求正文

编辑

定义规则值的 JSON 对象

所有规则类型所需的字段

编辑
名称 类型 描述

description

字符串

规则的描述。

name

字符串

规则的名称。

risk_score

整数

警报严重程度的数字表示，范围从 0 到 100，其中

  • 0 - 21 表示低严重性
  • 22 - 47 表示中严重性
  • 48 - 73 表示高严重性
  • 74 - 100 表示严重严重性

severity

字符串

规则生成的警报的严重级别，必须是以下之一

  • low：引起关注但通常不被视为安全事件的警报
  • medium：需要调查的警报
  • high：需要立即调查的警报
  • critical：表明很可能已发生安全事件的警报

type

字符串

规则基于的数据类型

  • eql：EQL 查询（请参阅 事件查询语言）。
  • esql：ES|QL 查询（请参阅 Elasticsearch 查询语言）。
  • query：带或不带其他过滤器的查询。
  • saved_query：已保存的搜索，在 saved_id 字段中标识。
  • machine_learning：基于机器学习作业的异常分数的规则。
  • threat_match：将事件值与指定 Elasticsearch 索引中的值匹配的规则。
  • threshold：基于 query 匹配指定字段次数的规则。
  • new_terms：针对以前从未见过值的规则发出警报

查询、指标匹配、阈值、新术语、事件关联和 ES|QL 规则所需的字段

编辑
名称 类型 描述

query

字符串

规则用于创建警报的 查询。

  • 对于指标匹配规则，仅使用查询的结果来确定是否生成警报。
  • ES|QL 规则有其他查询要求。有关更多信息，请参阅 创建 ES|QL 规则。

阈值规则所需的字段

编辑
名称 类型 描述

threshold

对象

定义生成警报的字段和阈值，其中

  • cardinality（长度为 1 的数组）：应用基数的字段。
  • cardinality.field（字符串，必填）：计算和比较基数的字段。
  • cardinality.value（整数，必填）：根据 cardinality.field 的唯一值数量生成的警报的阈值。
  • field（字符串或字符串数组，必填）：应用阈值的字段。如果指定空数组 ([])，则在查询返回至少 value 字段中指定的数量的结果时生成警报。
  • value（整数，必填）：生成警报的阈值。

已保存查询规则所需的字段

编辑
名称 类型 描述

saved_id

字符串

规则用于创建警报的 Kibana 已保存搜索。

事件关联规则所需的字段

编辑
名称 类型 描述

language

字符串

必须为 eql。

ES|QL 规则所需的字段

编辑
名称 类型 描述

language

字符串

必须为 esql。

机器学习规则所需的字段

编辑
名称 类型 描述

anomaly_threshold

整数

规则创建警报的异常分数阈值。有效值介于 0 到 100 之间。

machine_learning_job_id

字符串数组

规则监视异常分数的机器学习作业 ID。

指标匹配规则所需的字段

编辑
名称 类型 描述

threat_index

字符串数组

用于检查哪些字段值生成警报的 Elasticsearch 索引。

threat_query

字符串

用于确定 Elasticsearch 索引中哪些字段用于生成警报的查询。

threat_mapping

对象数组

定义源事件字段与 Elasticsearch 威胁索引中的值之间映射的 entries 对象数组。每个 entries 对象都必须包含以下字段

  • field：规则运行的事件索引中的字段
  • type：必须为 mapping
  • value：Elasticsearch 威胁索引中的字段

您可以使用布尔 and 和 or 逻辑来定义匹配字段和值生成警报的条件。同级 entries 对象使用 or 逻辑进行评估，而单个 entries 对象中的多个条目使用 and 逻辑进行评估。请参阅 下方 以获取使用 and 和 or 逻辑的示例。

新术语规则所需的字段

编辑
名称 类型 描述

new_terms_fields

字符串数组

要监视新值的字段。必须包含 1-3 个字段名称。

history_window_start

字符串

用于检查术语是否之前出现过的起始日期。支持相对日期，例如，now-30d 在检查术语是否为新术语时将搜索过去 30 天的数据。我们不建议使用绝对日期，因为随着时间的推移查询越来越多的数据会导致规则性能问题。

所有规则类型的可选字段

编辑
名称 类型 描述

操作

actions[]

定义在生成警报时采取的自动化操作（通知）的数组。

作者

字符串数组

规则的作者。

building_block_type

字符串

确定规则是否充当构建块。默认情况下，构建块警报不会在 UI 中显示。这些规则用作生成警报的其他规则的基础。其值必须为 default。有关更多信息，请参阅关于构建块规则。

启用

布尔值

确定规则是否启用。默认为 true。

误报

字符串数组

用于描述规则可能发出误报警报的常见原因的字符串数组。默认为空数组。

从

字符串

每次规则执行时分析数据的起始时间，使用日期数学范围。例如，now-4200s 表示规则分析其开始时间前 70 分钟的数据。默认为 now-6m（分析开始时间前 6 分钟的数据）。

间隔

字符串

规则执行的频率，使用日期数学范围。例如，"1h" 表示规则每小时运行一次。默认为 5m（5 分钟）。

许可证

字符串

规则的许可证。

max_signals

整数

规则在单个运行期间可以创建的最大警报数（规则的每次运行的最大警报数高级设置值）。默认为 100。

此设置可以被Kibana 配置设置xpack.alerting.rules.run.alerts.max覆盖，该设置确定 Kibana 警报框架中任何规则生成的最大警报数。例如，如果 xpack.alerting.rules.run.alerts.max设置为 1000，即使 max_signals 设置得更高，规则最多也只能生成 1000 个警报。

元数据

对象

规则元数据的占位符。

注意：当您保存对规则设置的更改时，此字段将被覆盖。

注释

字符串

有助于调查规则生成的警报的注释。

参考

字符串数组

包含关于规则的相关信息或参考的注释的数组。默认为空数组。

必需字段

对象数组

规则正常运行所需的 Elasticsearch 字段及其类型。该对象具有以下字段

  • name（字符串，必需）：字段的名称。
  • type（字符串，必需）：字段的数据类型。
  • ecs（布尔值，可选）：指示字段是否符合 ECS。此属性仅存在于响应中。其值是根据字段的名称和类型计算的。

注意：required_fields的值不会影响规则的行为，并且错误地指定它不会导致规则失败。使用 required_fields作为信息属性来记录规则期望数据中存在的字段。

规则ID

字符串

用于标识规则的唯一 ID。例如，当规则从第三方安全解决方案转换而来时。在未提供时自动创建。

设置

字符串

使用有关规则先决条件（例如所需的集成、配置步骤以及规则正常运行所需的任何其他内容）的说明填充规则的设置指南。

标签

字符串数组

包含单词和短语的字符串数组，用于帮助对规则进行分类、过滤和搜索。默认为空数组。

威胁

threat[]

包含有关规则监控的威胁类型的攻击信息的 对象，请参阅ECS 威胁字段。默认为空数组。

节流

字符串

确定采取操作的频率

规则级别的 throttle字段在 Elastic Security 8.8 中已弃用，并将至少在未来 12 个月内保持有效。

在 Elastic Security 8.8 及更高版本中，您可以使用（frequency）字段为各个操作定义频率。没有频率的操作将获取规则的 throttle字段的转换版本。在响应中，转换后的 throttle设置将显示在各个操作的 frequency字段中。

  • no_actions：从不
  • rule：每次检测到新警报时
  • 1h：每小时
  • 1d：每天
  • 7d：每周

当 actions 用于发送通知时，这是必需的。

版本

整数

规则的版本号。默认为 1。

调查字段

对象

指定突出显示的字段以实现个性化的警报调查流程

  • field_names：String[]，必需

相关集成

对象数组

规则依赖的Elastic 集成。该对象具有以下字段

  • package（字符串，必需）：集成包的名称，由Elastic 包注册表使用。
  • integration（字符串，可选）：集成的名称。对于只有一个集成且其名称与包名称匹配的包，此字段是可选的，但对于具有多个集成的包，此字段是必需的。
  • version：（字符串，必需）：语义版本控制格式中的集成（包含集成的包）版本约束。对于版本范围，必须使用波浪号或插入符号语法。例如，~1.2.3 是从 1.2.3 到小于 1.3.0 的任何补丁版本，而 ^1.2.3 是从 1.2.3` 到小于 2.0.0 的任何次要版本和补丁版本。

指标匹配规则的可选字段

编辑
名称 类型 描述

威胁过滤器

对象数组

用于从包含威胁值的 Elasticsearch 索引中过滤文档的查询和过滤器上下文数组。

威胁指标路径

字符串

类似于摄取处理器，用户可以使用此字段定义其威胁指标在其指标文档上的位置。默认为 threatintel.indicator。

查询、指标匹配、阈值和新术语规则的可选字段

编辑
名称 类型 描述

language

字符串

确定查询语言，该语言必须为 kuery 或 lucene。默认为 kuery。

事件关联、查询、阈值、指标匹配、新术语和 ES|QL 规则的可选字段

编辑
名称 类型 描述

过滤器

对象数组

用于定义何时从事件创建警报的条件的查询和过滤器上下文数组。默认为空数组。

此字段不支持 ES|QL 规则。

索引

字符串数组

规则在其上运行的索引。默认为 Kibana 高级设置页面上定义的安全解决方案索引（Kibana → 堆栈管理 → 高级设置 → securitySolution:defaultIndex）。

此字段不支持 ES|QL 规则。

风险评分映射

对象数组

使用源事件中的值覆盖生成的警报的 risk_score

  • field（字符串，必需）：用于覆盖默认 risk_score的源事件字段。此字段必须为整数。
  • operator（字符串，必需）：必须为 equals。
  • value（字符串，必需）：必须为空字符串（""）。

规则名称覆盖

字符串

设置源事件中哪个字段用于填充警报的 signal.rule.name值（在 UI 中，此值显示在规则页面上的规则列中）。在未指定的情况下，将使用规则的 name值。源字段必须为字符串数据类型。

严重性映射

对象数组

使用源事件中的值覆盖生成的警报的 severity

  • field（字符串，必需）：用于覆盖默认 severity的源事件字段。
  • operator（字符串，必需）：必须为 equals。
  • severity（字符串，必需）：映射的严重性值，必须为 low、medium、high或 critical。
  • value（字符串，必需）：用于确定 severity的字段值。

时间戳覆盖

字符串

设置用于查询索引的时间字段。在未指定的情况下，规则将查询 @timestamp字段。源字段必须为 Elasticsearch 日期数据类型。

异常列表

对象数组

包含异常容器的数组，这些容器定义了即使满足规则的其他条件也不会生成警报的异常。该对象具有以下字段

  • id（字符串，必需）：异常容器的 ID。
  • list_id（字符串，必填）：异常容器的列表 ID。
  • namespace_type（字符串，必填）：确定异常是否仅在规则的 Kibana 空间（single）中有效，还是在所有 Kibana 空间（agnostic）中有效。
  • type（字符串，必填）：异常类型，必须是检测规则异常（detection）或端点异常（endpoint）。

事件关联规则的可选字段

编辑
名称 类型 描述

event_category_field

字符串

包含事件分类，例如 process、file 或 network。此字段通常映射为 关键字族中的字段类型。默认为 event.category ECS 字段。

tiebreaker_field

字符串

如果事件具有相同的日期时间戳，则设置用于对事件进行排序（按升序、字典序）的辅助字段。

timestamp_field

字符串

包含用于对事件序列进行排序的事件日期时间戳。这与 timestamp_override 不同，后者用于在范围内查询事件。默认为 @timestamp ECS 字段。

查询、指标匹配、阈值、事件关联（仅非序列查询）、新术语、ES|QL 和机器学习规则的可选警报抑制字段

编辑

警报抑制处于事件关联规则的技术预览阶段。该功能可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。

查询、指标匹配、事件关联（仅非序列查询）、新术语、ES|QL 和机器学习规则
编辑
名称 类型 描述

alert_suppression

对象

定义警报抑制配置。可用字段

  • group_by（字符串数组，必填）：用于抑制警报的 1-3 个字段名称的数组。
  • duration（持续时间对象，可选）：警报将被抑制的时间段，从规则首次满足其条件并创建警报时开始。如果未指定，则仅在规则执行时抑制警报。

  • missing_fields_strategy（字符串，可选）：定义如何处理缺少抑制字段的事件。可能的值

    • doNotSuppress：为每个匹配的事件创建一个单独的警报。
    • suppress：为每个缺少字段的事件组创建一个警报。
阈值规则
编辑
名称 类型 描述

alert_suppression

对象

定义警报抑制配置。可用字段

  • duration（持续时间对象，必填）：警报将被抑制的时间段，从规则首次满足其条件并创建警报时开始。

actions 架构

编辑

所有字段都是必填的

名称 类型 描述

action_type_id

字符串

用于发送通知的连接器类型，可以是

  • .slack
  • .slack_api
  • .email
  • .index
  • .pagerduty
  • .swimlane
  • .webhook
  • .servicenow
  • .servicenow-itom
  • .servicenow-sir
  • .jira
  • .resilient
  • .opsgenie
  • .teams
  • .torq
  • .tines
  • .d3security

group

字符串

根据用例对操作进行分组（可选）。对于警报通知，请使用 default。

id

字符串

连接器 ID。

params

对象

包含允许的连接器字段的对象，根据连接器类型而有所不同

  • 对于 Slack

    • message（字符串，必填）：通知消息。

  • 对于电子邮件

    • to、cc、bcc（字符串）：发送通知的电子邮件地址。至少一个字段必须有值。
    • subject（字符串，可选）：电子邮件主题行。
    • message（字符串，必填）：电子邮件正文文本。

  • 对于 Webhook

    • body（字符串，必填）：JSON 有效负载。

  • 对于 PagerDuty

    • severity（字符串，必填）：警报通知的严重程度，可以是：Critical、Error、Warning 或 Info。
    • eventAction（字符串，必填）：事件 操作类型，可以是 trigger、resolve 或 acknowledge。
    • dedupKey（字符串，可选）：将具有相同 PagerDuty 警报的警报通知分组。
    • timestamp（DateTime，可选）：ISO-8601 格式的日期时间戳。
    • component（字符串，可选）：负责事件的源机器组件，例如 security-solution。
    • group（字符串，可选）：启用服务组件的逻辑分组。
    • source（字符串，可选）：受影响的系统。默认为操作的 Kibana 保存对象 ID。
    • summary（字符串，选项）：事件摘要。默认为 No summary provided。最大长度为 1024 个字符。
    • class（字符串，可选）：指示事件的类/类型的值。
可选的 action 字段
编辑
名称 类型 描述

frequency

字符串

包含操作频率的对象

  • summary（布尔值，必填）：定义是否将通知发送为警报摘要或为每个生成的警报发送通知。

  • notifyWhen（字符串，必填）：定义警报多久生成一次操作。有效值为

    • onActiveAlert：警报生成时运行操作。
    • onThrottleInterval：在指定的节流间隔上运行操作，并总结在此间隔期间生成的新的警报。
  • throttle（字符串，可选）：定义警报多久生成一次重复操作。此自定义操作间隔必须以秒、分钟、小时或天为单位指定。例如，10m 或 1h。仅当 notifyWhen 为 onThrottleInterval 时使用此属性。

alerts_filter

对象

包含操作的条件过滤器的对象

  • timeframe（对象，可选）：包含此操作可以运行的时间范围的对象。

    • days（整数数组，必填）：此操作可以运行的一周中的日期列表。一周中的日期表示为 1-7 之间的数字，其中 1 是星期一，7 是星期日。要选择一周中的所有日期，请输入一个空数组。

    • hours（对象，必填）：一天中此操作可以运行的小时数。一天中的小时数表示为 24 小时制格式的两个字符串 hh:mm。开始时间为 00:00，结束时间为 24:00，表示操作可以全天运行。

      • start（字符串，必填）
      • end（字符串，必填）
    • timezone（字符串，必填）：ISO 时区名称，例如 Europe/Madrid 或 America/New_York。UTC 或 UTC+1 等特定偏移量也可以使用，但缺乏内置的 DST。

  • query（对象，可选）：包含应用于操作并确定操作是否应运行的查询过滤器的对象。

    • kql（字符串，必填）：KQL 字符串。
    • filters（对象数组，必填）：过滤器对象，如 kbn-es-query 包中所定义。
警报通知占位符
编辑

您可以使用 mustache 语法 将变量添加到通知消息中。您选择的操作频率决定了您可以从中选择的变量。

以下变量可以传递给所有规则

请参阅 操作频率：警报摘要，以了解如果规则的操作频率为 警报摘要，则可以传递的其他变量。

  • {{context.alerts}}：检测到的警报数组
  • {{{context.results_link}}}：Kibana 中警报的 URL
  • {{context.rule.anomaly_threshold}}：生成警报的异常阈值分数（仅限机器学习规则）
  • {{context.rule.description}}：规则描述
  • {{context.rule.false_positives}}：规则误报
  • {{context.rule.filters}}：规则过滤器（仅限查询规则）
  • {{context.rule.id}}：创建规则后返回的唯一规则 ID
  • {{context.rule.index}}：规则运行的索引（仅限查询规则）
  • {{context.rule.language}}：规则查询语言（仅限查询规则）
  • {{context.rule.machine_learning_job_id}}：关联的机器学习作业的 ID（仅限机器学习规则）
  • {{context.rule.max_signals}}：每个规则执行允许的最大警报数
  • {{context.rule.name}}：规则名称
  • {{context.rule.query}}：规则查询（仅限查询规则）
  • {{context.rule.references}}：规则参考

  • {{context.rule.risk_score}}：默认规则风险分数

    即使使用 风险分数覆盖 选项，此占位符也包含规则的默认值。

  • {{context.rule.rule_id}}：生成的或用户定义的规则 ID，可用作跨系统的标识符
  • {{context.rule.saved_id}}：保存的搜索 ID

  • {{context.rule.severity}}：默认规则严重程度

    即使使用了严重性覆盖选项，此占位符也包含规则的默认值。

  • {{context.rule.threat}}：规则威胁框架
  • {{context.rule.threshold}}：规则阈值（仅限阈值规则）
  • {{context.rule.timeline_id}}：关联的时间线 ID
  • {{context.rule.timeline_title}}：关联的时间线名称
  • {{context.rule.type}}：规则类型
  • {{context.rule.version}}：规则版本
  • {{date}}`：规则计划操作的日期
  • {{kibanaBaseUrl}}：配置的server.publicBaseUrl值，如果未配置则为空字符串
  • {{rule.id}}：规则的 ID
  • {{rule.name}}：规则的名称
  • {{rule.spaceId}}：规则的空间 ID
  • {{rule.tags}}：规则的标签
  • {{rule.type}}：规则类型
  • {{state.signals_count}}：检测到的警报数量

以下变量仅在规则的操作频率为每个警报时才能传递

  • {{alert.actionGroup}}：为规则计划操作的警报的操作组
  • {{alert.actionGroupName}}：为规则计划操作的警报的操作组的人类可读名称
  • {{alert.actionSubgroup}}：为规则计划操作的警报的操作子组
  • {{alert.id}}：为规则计划操作的警报的 ID
  • {{alert.flapping}}：警报上的一个标志，指示警报状态是否反复变化

响应操作模式

编辑

所有字段都是必填的

名称 类型 描述

action_type_id

字符串

您要添加到规则中的响应操作。

  • .osquery

  • .endpoint

    要了解有关使用隔离端点响应操作的要求的更多信息，请参阅隔离主机。

    主机隔离涉及将主机与网络隔离，以防止威胁进一步传播并限制潜在损害。请注意，自动主机隔离可能会导致意外后果，例如中断合法用户活动或阻止关键业务流程。

params

对象

包含允许的响应操作字段的对象，根据响应操作而有所不同。

Osquery

对于 Osquery（.osquery），请使用单个查询、保存的查询或查询包

  • query（字符串，可选）：要运行单个查询，请使用query字段并输入 SQL 查询。例如："query": "SELECT * FROM processes;"
  • saved_query_id（字符串，可选）：要运行保存的查询，请使用saved_query_id字段并指定保存的查询 ID。例如："saved_query_id": "processes_elastic"
  • packId（字符串，可选）：要指定查询包，请使用packId字段。例如："packId": "processes_elastic"
  • ecs_mapping（对象，必需）：将 Osquery 结果列或静态值映射到 Elastic Common Schema (ECS) 字段。例如："ecs_mapping": {"process.pid": {"field": "pid"}}
  • timeout（数字，可选）：查询停止运行之前的超时时间（以秒为单位）。覆盖默认超时允许您支持需要更多时间才能完成的查询。默认值和最小支持值为60。最大支持值为900。例如："timeout": 120。

有关运行 Osquery 查询和包的更多信息，请参阅创建实时查询 API。

端点安全

对于端点安全（.endpoint），请指定端点响应操作命令并提供可选注释

  • command（字符串，可选）：要运行端点响应操作，请为command字段指定一个值。例如："command": "isolate"

    唯一可用的操作是隔离主机响应操作（isolate）。

  • comment（字符串，可选）：添加一个说明或描述操作的注释。您可以在响应操作历史记录日志中找到您的注释。例如："comment": "Check processes"

threat模式

编辑

所有字段都是必填的

名称 类型 描述

框架

字符串

相关的攻击框架。

策略

对象

包含有关攻击类型的信息的对象

  • id - 字符串，必需
  • name - 字符串，必需
  • reference - 字符串，必需

技术

数组

包含有关攻击技术的数组（可选）

  • id - 字符串，必需
  • name - 字符串，必需
  • reference - 字符串，必需
  • subtechnique - 数组，可选

子技术

数组

包含有关攻击技术的更具体信息的数组

  • id - 字符串，必需
  • name - 字符串，必需
  • reference - 字符串，必需

仅在 UI 中显示使用 MITRE ATT&CKTM 框架描述的威胁（规则 → 检测规则 (SIEM) → 规则名称）。

alert_suppression.duration模式

编辑

所有字段都是必填的

名称 类型 描述

单位

字符串

时间单位。可能的值为：s（秒）、m（分钟）或h（小时）。

值

数字

正数。

请求示例

编辑

示例 1

搜索由 MS Office 启动的进程的查询规则

POST api/detection_engine/rules
{
  "rule_id": "process_started_by_ms_office_program",
  "risk_score": 50,
  "description": "Process started by MS Office program - possible payload",
  "interval": "1h", 
  "name": "MS Office child process",
  "severity": "low",
  "tags": [
   "child process",
   "ms office"
   ],
  "type": "query",
  "from": "now-70m", 
  "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
  "language": "kuery",
  "filters": [
     {
      "query": {
         "match": {
            "event.action": {
               "query": "Process Create (rule: ProcessCreate)",
               "type": "phrase"
            }
         }
      }
     }
  ],
  "required_fields": [
    { name: "process.parent.name", "type": "keyword" }
  ],
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2"}
  ],
  "enabled": false
}

规则每小时运行一次。

规则运行时会分析其开始时间前 70 分钟的数据。

如果规则在 15:00 开始运行，它将分析从 13:50 到 15:00 的数据。下次在 16:00 运行时，它将分析从 14:50 到 16:00 的数据。

示例 2

检测从同一外部源 IP 地址到 Windows 主机的多次登录失败尝试的阈值规则，并将severity值映射到自定义源事件字段

POST api/detection_engine/rules
{
  "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.",
  "enabled": true,
  "exceptions_list": [ 
    {
      "id": "int-ips",
      "namespace_type": "single",
      "type": "detection"
    }
  ],
  "from": "now-180s",
  "index": [
    "winlogbeat-*"
  ],
  "interval": "2m",
  "name": "Windows server prml-19",
  "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure",
  "required_fields": [
    { "name": "source.ip", "type": "ip" }
  ],
  "risk_score": 30,
  "rule_id": "liv-win-ser-logins",
  "severity": "low",
  "severity_mapping": [ 
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "low",
      "value": "Manchester"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "medium",
      "value": "London"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "high",
      "value": "Birmingham"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "critical",
      "value": "Wallingford"
    }
  ],
  "tags": [
    "Brute force"
  ],
  "threshold": { 
    "field": "source.ip",
    "value": 20
  },
  "type": "threshold"
}

用于排除内部 IP 地址的异常列表容器。

警报严重性级别根据定义的字段值进行映射。

当在至少 20 个结果中发现相同的源 IP 地址时，将生成警报。

示例 3

机器学习规则，当linux_anomalous_network_activity_ecs机器学习作业发现异常且阈值达到 70 或以上时，创建警报并发送 Slack 通知

POST api/detection_engine/rules
{
  "anomaly_threshold": 70,
  "rule_id": "ml_linux_network_high_threshold",
  "risk_score": 70,
  "machine_learning_job_id": "linux_anomalous_network_activity_ecs",
  "description": "Generates alerts when the job discovers anomalies over 70",
  "interval": "5m",
  "name": "Anomalous Linux network activity",
  "note": "Shut down the internet.",
  "setup": "This rule requires data coming in from Elastic Defend."
  "severity": "high",
  "tags": [
   "machine learning",
   "Linux"
   ],
  "type": "machine_learning",
  "from": "now-6m",
  "enabled": true,
  "actions": [
    {
      "action_type_id": ".slack",
      "group": "default",
      "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5",
      "params": {
        "message": "Urgent: {{context.rule.description}}"
      }
    }
  ]
}

示例 4

事件关联规则，当 Windows rundll32.exe进程进行异常网络连接时创建警报

POST api/detection_engine/rules
{
  "rule_id": "eql-outbound-rundll32-connections",
  "risk_score": 21,
  "description": "Unusual rundll32.exe network connection",
  "name": "rundll32.exe network connection",
  "severity": "low",
  "tags": [
   "EQL",
   "Windows",
   "rundll32.exe"
   ],
  "type": "eql",
  "language": "eql",
  "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
  "required_fields": [
    { "name": "event.type", "type": "keyword" },
    { "name": "process.args", "type": "keyword" },
    { "name": "process.args_count", "type": "long" },
    { "name": "process.entity_id", "type": "keyword" },
    { "name": "process.name", "type": "keyword" },
    { "name": "process.pe.original_file_name", "type": "keyword" }
  ]
}

示例 5

指标匹配规则，当以下任一条件为真时创建警报

  • 事件的目标 IP 地址和端口号与threat_index索引中的目标 IP和端口值匹配。
  • 事件的源 IP 地址与threat_index索引中的主机 IP 地址值匹配。
POST api/detection_engine/rules
{
    "type": "threat_match",
    "actions": [],
    "index": [
        "packetbeat-*"
    ],
    "query": "destination.ip:* or host.ip:*",
    "threat_index": [
        "ip-threat-list" 
    ],
    "threat_query": "*:*", 
    "threat_mapping": [
        {
            "entries": [ 
                {
                    "field": "destination.ip",
                    "type": "mapping",
                    "value": "destination.ip"
                },
                {
                    "field": "destination.port",
                    "type": "mapping",
                    "value": "destination.port"
                }
            ]
        },
        {
            "entries": [ 
                {
                    "field": "source.ip",
                    "type": "mapping",
                    "value": "host.ip"
                }
            ]
        }
    ],
    "required_fields": [
      { "name": "destination.ip", "type": "ip" },
      { "name": "destination.port", "type": "long" },
      { "name": "host.ip", "type": "ip" }
    ],
    "risk_score": 50,
    "severity": "medium",
    "name": "Bad IP threat match",
    "description": "Checks for bad IP addresses listed in the ip-threat-list index"
}

用于匹配威胁值的 Elasticsearch 索引。

定义哪些威胁索引字段用于匹配值的查询。在此示例中，将使用ip-threat-list索引中的所有值。

单个entries元素中的多个对象使用and逻辑进行评估。在此示例中，事件的destination.ip和destination.port值都必须与ip-threat-list中的相应字段值匹配。

同级entries使用or逻辑进行评估。当至少一个entries对象评估为true时，将生成警报。

示例 6

新术语规则，当检测到用户的新的 IP 地址时创建警报

POST api/detection_engine/rules
{
  "risk_score": 21,
  "description": "Detects a user associated with a new IP address",
  "name": "New User IP Detected",
  "severity": "medium",
  "type": "new_terms",
  "language": "kuery",
  "query": "*",
  "new_terms_fields": ["user.id", "source.ip"],
  "history_window_start": "now-30d",
  "index": ["auditbeat*"],
  "required_fields": [
    { "name": "user.id", "type": "keyword" },
    { "name": "source.ip", "type": "ip" }
  ]
}

示例 7

ES|QL 规则，从与 Excel 父进程匹配的事件创建警报

POST api/detection_engine/rules
{
  "type": "esql",
  "language": "esql",
  "query": "from auditbeat-8.10.2 METADATA _id, _version, _index | where process.parent.name == \"EXCEL.EXE\"",
  "name": "Find Excel events",
  "description": "Find Excel events",
  "tags": [],
  "interval": "5m",
  "from": "now-360s",
  "to": "now",
  "enabled": false,
  "risk_score": 21,
  "severity": "low",
  "required_fields": [
    { "name": "process.parent.name", "type": "keyword" }
  ]
}

示例 8

搜索由 MS Office 启动的进程并通过process.parent.name字段在 5 小时的时间段内抑制警报的查询规则

POST api/detection_engine/rules
{
  "rule_id": "process_started_by_ms_office_program",
  "risk_score": 50,
  "description": "Process started by MS Office program - possible payload",
  "interval": "1h",
  "name": "MS Office child process",
  "severity": "low",
  "tags": [
   "child process",
   "ms office"
   ],
  "type": "query",
  "from": "now-70m",
  "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
  "language": "kuery",
  "filters": [
     {
      "query": {
         "match": {
            "event.action": {
               "query": "Process Create (rule: ProcessCreate)",
               "type": "phrase"
            }
         }
      }
     }
  ],
  "enabled": false,
  "alert_suppression": {
    "duration": { "unit": "h", "value": 5 },
    "group_by": [
        "process.parent.name"
    ],
    "missing_fields_strategy": "suppress"
  }
}

响应代码

编辑
200
指示调用成功。

响应有效负载

编辑

一个 JSON 对象，其中包含唯一的 ID、规则创建的时间及其版本号。如果请求有效负载未包含rule_id字段，则也会生成唯一的规则 ID。

查询规则的响应示例

{
  "created_at": "2020-04-07T14:51:09.755Z",
  "updated_at": "2020-04-07T14:51:09.970Z",
  "created_by": "elastic",
  "description": "Process started by MS Office program - possible payload",
  "enabled": false,
  "false_positives": [],
  "from": "now-70m",
  "id": "6541b99a-dee9-4f6d-a86d-dbd1869d73b1",
  "immutable": false,
  "interval": "1h",
  "rule_id": "process_started_by_ms_office_program",
  "max_signals": 100,
  "risk_score": 50,
  "name": "MS Office child process",
  "references": [],
  "severity": "low",
  "updated_by": "elastic",
  "tags": [
    "child process",
    "ms office"
  ],
  "to": "now",
  "type": "query",
  "threat": [],
  "version": 1,
  "actions": [],
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "query": "Process Create (rule: ProcessCreate)",
            "type": "phrase"
          }
        }
      }
    }
  ],
  "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE",
  "language": "kuery",
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" },
    { "package": "azure", "version": "^1.11.4", "integration": "graphactivitylogs" }
  ],
  "required_fields": [
    { "name": "process.parent.name", "type": "keyword", "ecs": true }
  ],
  "setup": ""
}

机器学习作业规则的响应示例

{
  "created_at": "2020-04-07T14:45:15.679Z",
  "updated_at": "2020-04-07T14:45:15.892Z",
  "created_by": "elastic",
  "description": "Generates alerts when the job discovers anomalies over 70",
  "enabled": true,
  "false_positives": [],
  "from": "now-6m",
  "id": "83876f66-3a57-4a99-bf37-416494c80f3b",
  "immutable": false,
  "interval": "5m",
  "rule_id": "ml_linux_network_high_threshold",
  "max_signals": 100,
  "risk_score": 70,
  "name": "Anomalous Linux network activity",
  "references": [],
  "severity": "high",
  "updated_by": "elastic",
  "tags": [
    "machine learning",
    "Linux"
  ],
  "to": "now",
  "type": "machine_learning",
  "threat": [],
  "version": 1,
  "actions": [
    {
      "action_type_id": ".slack",
      "group": "default",
      "id": "5ad22cd5-5e6e-4c6c-a81a-54b626a4cec5",
      "params": {
        "message": "Urgent: {{context.rule.description}}"
      },
      "frequency": {
        "summary": true,
        "notifyWhen": "onActiveAlert",
        "throttle": null
      }
    }
  ],
  "note": "Shut down the internet.",
  "status": "going to run",
  "status_date": "2020-04-07T14:45:21.685Z",
  "anomaly_threshold": 70,
  "machine_learning_job_id": "linux_anomalous_network_activity_ecs",
  "related_integrations": [],
  "required_fields": [],
  "setup": ""
}

阈值规则的响应示例

{
  "author": [],
  "created_at": "2020-07-22T10:27:23.486Z",
  "updated_at": "2020-07-22T10:27:23.673Z",
  "created_by": "elastic",
  "description": "Detects when there are 20 or more failed login attempts from the same IP address with a 2 minute time frame.",
  "enabled": true,
  "false_positives": [],
  "from": "now-180s",
  "id": "15dbde26-b627-4d74-bb1f-a5e0ed9e4993",
  "immutable": false,
  "interval": "2m",
  "rule_id": "liv-win-ser-logins",
  "max_signals": 100,
  "risk_score": 30,
  "risk_score_mapping": [],
  "name": "Windows server prml-19",
  "references": [],
  "severity": "low",
  "severity_mapping": [
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "low",
      "value": "Manchester"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "medium",
      "value": "London"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "high",
      "value": "Birmingham"
    },
    {
      "field": "source.geo.city_name",
      "operator": "equals",
      "severity": "critical",
      "value": "Wallingford"
    }
  ],
  "updated_by": "elastic",
  "tags": [
    "Brute force"
  ],
  "to": "now",
  "type": "threshold",
  "threat": [],
  "version": 1,
  "exceptions_list": [
    {
      "id": "int-ips",
      "namespace_type": "single",
      "type": "detection"
    }
  ],
  "actions": [],
  "index": [
    "winlogbeat-*"
  ],
  "query": "host.name:prml-19 and event.category:authentication and event.outcome:failure",
  "language": "kuery",
  "threshold": {
    "field": "source.ip",
    "value": 20
  },
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" }
  ],
  "required_fields": [
    { "name": "source.ip", "type": "ip", "ecs": true }
  ],
  "setup": ""
}

EQL 规则的响应示例

{
  "author": [],
  "created_at": "2020-10-05T09:06:16.392Z",
  "updated_at": "2020-10-05T09:06:16.403Z",
  "created_by": "elastic",
  "description": "Unusual rundll32.exe network connection",
  "enabled": true,
  "false_positives": [],
  "from": "now-6m",
  "id": "93808cae-b05b-4dc9-8479-73574b50f8b1",
  "immutable": false,
  "interval": "5m",
  "rule_id": "eql-outbound-rundll32-connections",
  "max_signals": 100,
  "risk_score": 21,
  "risk_score_mapping": [],
  "name": "rundll32.exe network connection",
  "references": [],
  "severity": "low",
  "severity_mapping": [],
  "updated_by": "elastic",
  "tags": [
    "EQL",
    "Windows",
    "rundll32.exe"
  ],
  "to": "now",
  "type": "eql",
  "threat": [],
  "version": 1,
  "exceptions_list": [],
  "throttle": "no_actions",
  "query": "sequence by process.entity_id with maxspan=2h [process where event.type in (\"start\", \"process_started\") and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\") and ((process.args == \"rundll32.exe\" and process.args_count == 1) or (process.args != \"rundll32.exe\" and process.args_count == 0))] [network where event.type == \"connection\" and (process.name == \"rundll32.exe\" or process.pe.original_file_name == \"rundll32.exe\")]",
  "language": "eql",
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" }
  ],
  "required_fields": [
    { "name": "event.type", "type": "keyword", "ecs": true },
    { "name": "process.args", "type": "keyword", "ecs": true },
    { "name": "process.args_count", "type": "long", "ecs": true },
    { "name": "process.entity_id", "type": "keyword", "ecs": true },
    { "name": "process.name", "type": "keyword", "ecs": true },
    { "name": "process.pe.original_file_name", "type": "keyword", "ecs": true }
  ],
  "setup": ""
}

指标匹配规则的响应示例

{
  "author": [],
  "created_at": "2020-10-06T07:07:58.227Z",
  "updated_at": "2020-10-06T07:07:58.237Z",
  "created_by": "elastic",
  "description": "Checks for bad IP addresses listed in the ip-threat-list index",
  "enabled": true,
  "false_positives": [],
  "from": "now-6m",
  "id": "d5daa13f-81fb-4b13-be2f-31011e1d9ae1",
  "immutable": false,
  "interval": "5m",
  "rule_id": "608501e4-c768-4f64-9326-cec55b5d439b",
  "max_signals": 100,
  "risk_score": 50,
  "risk_score_mapping": [],
  "name": "Bad IP threat match",
  "references": [],
  "severity": "medium",
  "severity_mapping": [],
  "updated_by": "elastic",
  "tags": [],
  "to": "now",
  "type": "threat_match",
  "threat": [],
  "version": 1,
  "exceptions_list": [],
  "index": [
    "packetbeat-*"
  ],
  "query": "destination.ip:* or host.ip:*",
  "language": "kuery",
  "threat_query": "*:*",
  "threat_index": [
    "ip-threat-list"
  ],
  "threat_mapping": [
    {
      "entries": [
        {
          "field": "destination.ip",
          "type": "mapping",
          "value": "destination.ip"
        },
        {
          "field": "destination.port",
          "type": "mapping",
          "value": "destination.port"
        }
      ]
    },
    {
      "entries": [
        {
          "field": "source.ip",
          "type": "mapping",
          "value": "host.ip"
        }
      ]
    }
  ],
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" }
  ],
  "required_fields": [
    { "name": "destination.ip", "type": "ip", "ecs": true },
    { "name": "destination.port", "type": "long", "ecs": true },
    { "name": "host.ip", "type": "ip", "ecs": true }
  ],
  "setup": ""
}

新术语规则的响应示例

{
  "author": [],
  "created_at": "2020-10-06T07:07:58.227Z",
  "updated_at": "2020-10-06T07:07:58.237Z",
  "created_by": "elastic",
  "description": "Detects a user associated with a new IP address",
  "enabled": true,
  "false_positives": [],
  "from": "now-6m",
  "id": "eb7225c0-566b-11ee-8b4f-bbf3afdeb9f4",
  "immutable": false,
  "interval": "5m",
  "rule_id": "c6f5d0bc-7be9-47d4-b2f3-073d22641e30",
  "max_signals": 100,
  "risk_score": 21,
  "risk_score_mapping": [],
  "name": "New User IP Detected",
  "references": [],
  "severity": "medium",
  "severity_mapping": [],
  "updated_by": "elastic",
  "tags": [],
  "to": "now",
  "type": "new_terms",
  "threat": [],
  "version": 1,
  "exceptions_list": [],
  "index": [
    "auditbeat*"
  ],
  "query": "*",
  "language": "kuery",
  "new_terms_fields": ["user.id", "source.ip"],
  "history_window_start": "now-30d",
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" }
  ],
  "required_fields": [
    { "name": "user.id", "type": "keyword", "ecs": true },
    { "name": "source.ip", "type": "ip", "ecs": true }
  ],
  "setup": ""
}

ES|QL 规则的响应示例

{
  "name": "Find Excel events",
  "description": "Find Excel events",
  "risk_score": 21,
  "severity": "low",
  "output_index": "",
  "tags": [],
  "interval": "5m",
  "enabled": false,
  "author": [],
  "false_positives": [],
  "from": "now-360s",
  "max_signals": 100,
  "risk_score_mapping": [],
  "severity_mapping": [],
  "threat": [],
  "to": "now",
  "references": [],
  "version": 1,
  "exceptions_list": [],
  "actions": [],
  "id": "d0f20490-6da4-11ee-b85e-09e9b661f2e2",
  "updated_at": "2023-10-18T10:55:14.269Z",
  "updated_by": "elastic",
  "created_at": "2023-10-18T10:55:14.269Z",
  "created_by": "elastic",
  "revision": 0,
  "rule_id": "e4b53a89-debd-4a0d-a3e3-20606952e589",
  "immutable": false,
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2" }
  ],
  "required_fields": [
    { "name": "process.parent.name", "type": "keyword", "ecs": true }
  ],
  "setup": "",
  "type": "esql",
  "language": "esql",
  "query": "from auditbeat-8.10.2 METADATA _id | where process.parent.name == \"EXCEL.EXE\""
}
« 检测 API 获取规则 »