« 查找规则 删除规则 »
Elastic 文档 ›Elastic 安全解决方案 [8.14] ›Elastic 安全 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。

meta

对象

用于保存关于规则的元数据的占位符。

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

note

字符串

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

references

字符串数组

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

setup

字符串

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

tags

字符串数组

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

threat

threat[]

包含关于规则监视的威胁类型的攻击信息的 Object，参见 ECS 威胁字段。默认为空数组。

throttle

字符串

确定操作的执行频率

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

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

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

当 actions 用于发送通知时需要。

版本

整数

规则的版本号。如果未提供，则规则的版本号将加 1。

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

威胁匹配规则的可选字段编辑

名称 类型 描述

威胁过滤器

对象数组

查询和过滤器上下文 用于从包含威胁值的 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 对象时需要这些字段

名称 类型 描述

action_type_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 (Boolean，必需): 定义是否将通知作为警报摘要发送，还是针对每个生成的警报发送。

  • notifyWhen (String，必需`): 定义警报生成操作的频率。有效值为

    • onActiveAlert: 生成警报时运行操作。
    • onThrottleInterval: 在指定的节流间隔上运行操作，并汇总在该间隔内生成的新警报。
  • throttle (String，可选): 定义警报生成重复操作的频率。此自定义操作间隔必须以秒、分钟、小时或天为单位指定。例如，10m 或 1h。仅当 notifyWhen 为 onThrottleInterval 时使用此属性。

警报过滤器

对象

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

  • timeframe (Object，可选): 包含此操作可以运行的时间范围的对象。

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

    • hours (Object，必需): 此操作可以运行的一天中的小时数。一天中的小时数表示为 24 小时制的两个字符串，格式为 hh:mm。如果开始时间为 00:00，结束时间为 24:00，则表示操作可以全天运行。

      • start (String，必需)
      • end (String，必需)
    • timezone (String，必需): ISO 时区名称，例如 Europe/Madrid 或 America/New_York。UTC 或 UTC+1 等特定偏移量也适用，但缺少内置的 DST。

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

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

threat 架构编辑

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

名称 类型 描述

框架

字符串

相关的攻击框架。

战术

对象

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

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

技术

对象

包含有关攻击技术的信息的对象

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

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

查询、指标匹配、阈值、事件关联（仅非序列查询）和新词条规则的可选警报抑制字段编辑

警报抑制功能目前处于技术预览阶段，适用于阈值、指标匹配、事件关联和新术语规则。此功能可能会在未来版本中发生更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 约束。

查询、指标匹配、事件关联（仅限非序列查询）和新术语规则编辑
名称 类型 描述

alert_suppression

对象

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

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

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

    • 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": [],       
  "required_fields": [],            
  "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 约束。 这些字段正在开发中，其使用或模式可能会更改: related_integrations, required_fields, 和 execution_summary.
« 查找规则 删除规则 »