« 查找规则 删除规则 »
Elastic 文档 ›Elastic 安全解决方案 [8.16] ›Elastic 安全 API ›检测 API

更新规则

编辑

更新规则

编辑

新的 API 参考

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

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

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

更新现有的检测规则。

您可以使用 PUT 或 PATCH 方法更新规则，其中

  • PUT 替换原始规则并删除未指定的字段。
  • PATCH 更新指定的字段。

请求 URL

编辑

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

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

请求正文

编辑

一个包含以下内容的 JSON 对象：

  • 您要更新的规则的 id 或 rule_id 字段。
  • 您要修改的字段。

如果您调用 PUT 来更新规则，则所有未指定的字段都将被删除。您无法修改 id 或 rule_id 值。

对于 PATCH 调用，可以修改任何字段，而对于 PUT 调用，某些字段是必需的。

PUT 调用所需的字段

编辑
名称 类型 描述

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：对以前从未见过的值发出警报的规则

查询、威胁匹配、阈值和新术语规则 PUT 调用所需的字段

编辑
名称 类型 描述

query

字符串

规则用于创建警报的 查询。对于威胁匹配规则，仅使用查询的结果来确定是否生成警报。

阈值规则 PUT 调用所需的字段

编辑
名称 类型 描述

threshold

对象

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

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

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

编辑
名称 类型 描述

saved_id

字符串

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

EQL 规则 PUT 调用所需的字段

编辑
名称 类型 描述

language

字符串

必须为 eql。

ES|QL 规则 PUT 调用所需的字段

编辑
名称 类型 描述

language

字符串

必须为 esql。

机器学习规则 PUT 调用所需的字段

编辑
名称 类型 描述

anomaly_threshold

整数

规则创建警报的异常分数阈值。有效值为 0 到 100。

machine_learning_job_id

字符串

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

威胁匹配规则 PUT 调用所需的字段

编辑
名称 类型 描述

threat_index

字符串数组

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

threat_query

字符串

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

threat_mapping

对象数组

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

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

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

新术语规则 PUT 调用所需的字段

编辑
名称 类型 描述

new_terms_fields

字符串数组

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

history_window_start

字符串

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

所有规则类型的可选字段

编辑
名称 类型 描述

actions

actions[]

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

author

字符串数组

规则的作者。

building_block_type

字符串

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

enabled

布尔值

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

false_positives

字符串数组

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

from

字符串

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

interval

字符串

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

license

字符串

规则的许可证。

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 用作信息属性来记录规则期望数据中存在的字段。

设置

字符串

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

标签

字符串数组

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

威胁

threat[]

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

节流

字符串

确定采取操作的频率

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

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

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

当使用 actions 发送通知时，此项为必需。

版本

整数

规则的版本号。如果未提供此版本号，则规则的版本号将递增 1。

PATCH 调用启用和禁用规则不会递增其版本号。

相关集成

对象数组

规则依赖的 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。

EQL、查询、阈值、指标匹配、新术语规则和 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）。

EQL 规则的可选字段

编辑
名称 类型 描述

事件类别字段

字符串

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

决胜符字段

字符串

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

时间戳字段

字符串

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

actions 架构

编辑

调用 PUT 修改 actions 对象时，这些字段是必需的

名称 类型 描述

操作类型 ID

字符串

用于发送通知的操作类型，可以是

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

组

字符串

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

ID

字符串

连接器 ID。

参数

对象

包含允许的连接器字段的对象，根据连接器类型而异

  • 对于 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字段
编辑
名称 类型 描述

频率

字符串

包含操作频率的对象

  • 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等特定偏移量也可以使用，但缺乏内置的夏令时。

  • query (对象，可选): 包含应用于操作并确定操作是否应运行的查询筛选器的对象。

    • kql (字符串，必填): KQL字符串。
    • filters (对象数组，必填): 筛选器对象，如kbn-es-query包中所定义。

threat模式

编辑

调用PUT修改threat对象时，需要这些字段

名称 类型 描述

框架

字符串

相关的攻击框架。

策略

对象

包含攻击类型信息的对象

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

技术

对象

包含攻击技术信息的对象

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

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

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

编辑

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

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

alert_suppression

对象

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

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

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

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

alert_suppression

对象

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

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

示例请求

编辑

更新threat对象

PATCH api/detection_engine/rules
{
  "rule_id": "process_started_by_ms_office_program_possible_payload",
  "threat": [
   {
      "framework": "MITRE ATT&CK",
      "tactic": {
         "id": "TA0001",
         "reference": "https://attack.mitre.org/tactics/TA0001",
         "name": "Initial Access"
      },
      "technique": [
         {
            "id": "T1193",
            "name": "Spearphishing Attachment",
            "reference": "https://attack.mitre.org/techniques/T1193"
         }
      ]
   }
  ]
}

响应代码

编辑
200
指示调用成功。

响应有效负载

编辑

规则更新后的JSON对象，包括规则更新时间和递增的版本号。

示例响应

{
  "created_at": "2020-01-05T09:56:11.805Z",
  "updated_at": "2020-01-05T09:59:59.129Z",
  "created_by": "elastic",
  "description": "Process started by MS Office program - possible payload",
  "enabled": false,
  "false_positives": [],
  "filters": [
    {
      "query": {
        "match": {
          "event.action": {
            "query": "Process Create (rule: ProcessCreate)",
            "type": "phrase"
          }
        }
      }
    }
  ],
  "from": "now-6m",
  "id": "4f228868-9928-47e4-9785-9a1a9b520c7f",
  "interval": "5m",
  "rule_id": "process_started_by_ms_office_program_possible_payload",
  "language": "kuery",
  "max_signals": 100,
  "risk_score": 50,
  "name": "MS Office child process",
  "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",
  "references": [],
  "severity": "low",
  "updated_by": "elastic",
  "tags": [
    "child process",
    "ms office"
  ],
  "related_integrations": [
    { "package": "o365", "version": "^2.3.2"}
  ],
  "required_fields": [
    { "name": "process.parent.name", "type": "keyword", "ecs": true }
  ],
  "setup": "",
  "type": "query",
  "threat": [
    {
      "framework": "MITRE ATT&CK",
      "tactic": {
        "id": "TA0001",
        "reference": "https://attack.mitre.org/tactics/TA0001",
        "name": "Initial Access"
      },
      "technique": [
        {
          "id": "T1193",
          "name": "Spearphishing Attachment",
          "reference": "https://attack.mitre.org/techniques/T1193"
        }
      ]
    }
  ],
  "execution_summary": {                      
    "last_execution": {
      "date": "2022-03-23T16:06:12.787Z",
      "status": "partial failure",
      "status_order": 20,
      "message": "This rule attempted to query data from Elasticsearch indices listed in the \"Index pattern\" section of the rule definition, but no matching index was found.",
      "metrics": {
          "total_search_duration_ms": 135,
          "total_indexing_duration_ms": 15,
          "execution_gap_duration_s": 0,
      }
    }
  },
  "version": 2
}

[开发] 此功能正在开发中，可能会在将来的版本中更改或完全删除。这些功能不受支持，也不受正式GA功能的支持SLA的约束。 这些字段正在开发中，其用法或模式可能会更改：execution_summary。
« 查找规则 删除规则 »