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

meta

对象

规则元数据的占位符。

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

note

字符串

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

references

字符串[]

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

required_fields

对象[]

规则要起作用所需的 Elasticsearch 字段及其类型。该对象具有以下字段

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

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

setup

字符串

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

tags

字符串[]

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

威胁

threat[]

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

节流

字符串

确定执行操作的频率

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

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

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

当使用 actions 发送通知时，此字段为必填项。

版本

整数

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

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

related_integrations

对象[]

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

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

威胁匹配规则的可选字段

编辑
名称 类型 描述

threat_filters

对象[]

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

threat_indicator_path

字符串

与 ingest processor 非常相似，用户可以使用此字段定义其威胁指示器在指示器文档中的位置。默认为 threatintel.indicator。

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

编辑
名称 类型 描述

language

字符串

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

EQL、查询、阈值、指示器匹配、新术语规则和 ES|QL 规则的可选字段

编辑
名称 类型 描述

filters

对象[]

用于定义从事件创建警报的条件的查询和筛选上下文数组。默认为空数组。

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

index

字符串[]

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

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

risk_score_mapping

对象[]

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

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

rule_name_override

字符串

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

severity_mapping

对象[]

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

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

timestamp_override

字符串

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

exceptions_list

对象[]

异常容器的数组，用于定义防止规则生成警报的异常，即使满足其其他条件也是如此。该对象具有以下字段

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

EQL 规则的可选字段

编辑
名称 类型 描述

event_category_field

字符串

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

tiebreaker_field

字符串

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

timestamp_field

字符串

包含用于对一系列事件进行排序的事件时间戳。这与 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

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 (日期时间，可选)：ISO-8601 格式的时间戳。
    • component (字符串，可选)：负责该事件的源机器组件，例如 security-solution。
    • group (字符串，可选)：启用服务组件的逻辑分组。
    • source (字符串，可选)：受影响的系统。默认为操作的 Kibana 保存的对象 ID。
    • summary (字符串，可选)：事件摘要。默认为 未提供摘要。最大长度为 1024 个字符。
    • class (字符串，可选)：指示事件的类/类型的值。
可选的 action 字段
编辑
名称 类型 描述

frequency

字符串

包含操作频率的对象

  • summary (布尔值，必需)：定义是将通知作为警报摘要发送，还是为每个生成的警报发送。

  • notifyWhen (字符串，必需`)：定义警报生成操作的频率。有效值包括

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

alerts_filter

对象

包含操作的条件筛选器的对象

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

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

    • hours (对象，必需): 此操作可以运行的每天的小时数。每天的小时数用两个字符串表示，格式为 hh:mm，采用 24 小时制。起始时间为 00:00，结束时间为 24:00 表示该操作可以全天运行。

      • start (字符串，必需)
      • end (字符串，必需)
    • timezone (字符串，必需): 一个 ISO 时区名称，例如 Europe/Madrid 或 America/New_York。诸如 UTC 或 UTC+1 之类的特定偏移量也可以使用，但缺少内置的夏令时 (DST)。

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

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

threat 架构

编辑

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

名称 类型 描述

framework

字符串

相关的攻击框架。

tactic

对象

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

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

technique

对象

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

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

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

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

编辑

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

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

alert_suppression

对象

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

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

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

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

alert_suppression

对象

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

* duration (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。
« 查找规则 删除规则 »