« 删除规则 索引端点 »
Elastic 文档 ›Elastic 安全解决方案 [8.14] ›Elastic 安全 API ›检测 API

批量规则操作

编辑

批量规则操作编辑

您可以批量创建、更新和删除规则。

批量创建编辑

此 API 自 8.2 版本起已弃用，并计划于 2024 年停止使用。请改用 批量操作 API。

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

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

创建新规则。

请求 URL编辑

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

请求主体编辑

规则的 JSON 数组，其中每个规则都包含 必需字段。

示例请求编辑
POST api/detection_engine/rules/_bulk_create
[
  {
    "rule_id": "process_started_by_ms_office_program_possible_payload",
    "risk_score": 50,
    "description": "Process started by MS Office program - possible payload",
    "interval": "5m",
    "name": "MS Office child process",
    "severity": "low",
    "tags": [
     "child process",
     "ms office"
     ],
    "type": "query",
    "from": "now-6m",
    "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
  },
  {
    "name": "Second bulk rule",
    "description": "Query with a rule_id for referencing an external id",
    "rule_id": "query-rule-id-2",
    "risk_score": 2,
    "severity": "low",
    "type": "query",
    "from": "now-6m",
    "query": "user.name: root or user.name: admin"
  }
]
响应代码编辑
200
表示成功调用。
响应有效载荷编辑

一个 JSON 数组，其中包含每个规则的唯一 ID。所有未包含 rule_id 字段的规则都会生成唯一的规则 ID。

批量删除编辑

此 API 自 8.2 版本起已弃用，并计划于 2024 年停止使用。请改用 批量操作 API。

删除多个规则。

请求 URL编辑

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

请求主体编辑

一个 JSON 数组，包含要删除的规则的 id 或 rule_id 字段。

示例请求编辑
DELETE api/detection_engine/rules/_bulk_delete
[
  {
    "rule_id": "process_started_by_ms_office_program_possible_payload"
  },
  {
    "id": "51658332-a15e-4c9e-912a-67214e2e2359"
  }
]
响应代码编辑
200
表示成功调用。
响应有效载荷编辑

一个 JSON 数组，包含已删除的规则。

批量更新编辑

此 API 自 8.2 版本起已弃用，并计划于 2024 年停止使用。请改用 批量操作 API。

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

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

更新多个规则。

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

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

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

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

请求主体编辑

一个 JSON 数组，其中每个元素都包含

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

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

对于 PATCH 调用，可以修改任何字段。对于 PUT 调用，某些字段是必需的（有关必需字段的列表，请参阅 更新规则）。

示例请求编辑
PATCH api/detection_engine/rules/_bulk_update
[
  {
    "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"
           }
        ]
     }
   ],
    "rule_id": "process_started_by_ms_office_program_possible_payload"
  },
  {
    "name": "New name",
    "id": "56b22b65-173e-4a5b-b27a-82599cb1433e"
  }
]
响应代码编辑
200
表示成功调用。
响应有效载荷编辑

一个 JSON 数组，包含已更新的规则。

批量操作编辑

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

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

将批量操作应用于多个规则。批量操作将应用于匹配筛选器的所有规则，或应用于其 ID 的规则列表。

请求 URL编辑

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

URL 查询参数编辑
名称 类型 说明 必需

dry_run

布尔值

为请求调用启用 试运行模式。

否
请求主体编辑

一个 JSON 对象，包含以下属性

名称 类型 说明 必需

query

字符串

用于匹配规则的 KQL 搜索查询。

否

ids

字符串[]

将应用批量操作的规则 ID 数组。仅当 query 属性未定义时有效。

否

action

枚举

要应用的批量操作。

可能的值

  • enable
  • disable
  • delete
  • duplicate
  • export
  • 编辑

是

编辑

BulkEditAction[]

编辑对象，描述应用更新操作。

否。

是，如果操作为 edit。

duplicate

BulkDuplicateAction[]

重复对象，描述应用更新操作。

否。

试运行模式编辑

启用试运行模式以验证批量操作是否可以应用于指定的规则。某些规则（例如预构建的 Elastic 规则）无法编辑，并且将在请求响应中返回错误。错误详细信息将包含解释、规则名称和/或 ID 以及其他故障排除信息。

要在请求上启用试运行模式，请在请求 URL 的末尾添加查询参数 dry_run=true。请求中指定的规则将被临时更新。这些更新不会写入 Elasticsearch。

试运行模式不支持 export 批量操作。请求响应中将返回 400 错误。

BulkDuplicateAction 对象编辑

  • include_exceptions 字段：布尔值。定义是否在重复的规则中包含异常。

BulkEditAction 对象编辑

  • type 字段：枚举。定义将在规则中更新的内容。
  • value 字段：任意。将在编辑操作中应用的值。
可能的 BulkEditAction 对象值编辑
type 字段 value 字段 说明

add_tags

字符串[]

向规则添加标签

delete_tags

字符串[]

删除规则的标签

set_tags

字符串[]

覆盖规则的标签

add_index_patterns

字符串[]

向规则添加索引模式

delete_index_patterns

字符串[]

删除规则的索引模式

set_index_patterns

字符串[]

覆盖规则的索引模式

set_timeline

{ timeline_id: 字符串; timeline_title: 字符串 }

覆盖规则的时间线模板

set_schedule

{ interval: 字符串; lookback: 字符串 }

覆盖规则的计划

interval: 规则执行的频率。例如，"1h" 表示规则每小时运行一次。

lookback: 规则分析的额外回溯时间。例如，"10m" 表示规则除了频率间隔外，还分析过去 10 分钟的数据。

如果 interval 设置为 "10m"，而 lookback 设置为 "1m"，则规则每 5 分钟运行一次，但会分析在过去 11 分钟内添加到索引中的文档。

interval 和 lookback 的格式均为 "{integer}{time_unit}"，其中接受的时间单位为 s（秒）、m（分钟）和 h（小时）。整数必须为正数且大于 0。示例："45s"、"30m"、"6h"

add_rule_actions

{ actions: actions[] , throttle: throttle }

向规则添加操作

set_rule_actions

{ actions: actions[] , throttle: throttle }

覆盖规则的现有操作

操作 按从旧到新的顺序显示在 edit 数组有效载荷的属性中。

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（DateTime，可选）：ISO-8601 格式时间戳。
    • component（字符串，可选）：负责事件的源机器组件，例如 security-solution。
    • group（字符串，可选）：允许对服务组件进行逻辑分组。
    • source（字符串，可选）：受影响的系统。默认值为操作的 Kibana 保存对象 ID。
    • summary（字符串，可选）：事件摘要。默认为 No summary provided。最大长度为 1024 个字符。
    • class（字符串，可选）：指示事件的类别/类型的值。
可选 action 字段edit
名称 类型 说明

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，意味着操作可以全天运行。

      要设置隔夜时间范围，请指定 end 时间，该时间早于 start 时间或等于 start 时间。例如：16:00 → 15:00 或 21:33 → 21:33。

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

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

    • kql（字符串，必需）：KQL 字符串。
    • filters（对象数组，必需）：过滤器对象，如 kbn-es-query 包中所定义。
throttle 架构edit

throttle 定义了规则的操作执行的最大间隔。它接受以下值

Elastic Security 8.8 中已弃用规则级 throttle 字段，并计划在 2024 年第四季度结束使用。

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

  • "rule"：在每次规则执行时执行操作
  • "1h"：每小时执行一次操作
  • "1d"：每天执行一次操作
  • "7d"：每周执行一次操作
示例请求edit

示例 1

以下请求激活具有 test 标签的所有规则

POST api/detection_engine/rules/_bulk_action
{
  "query": "alert.attributes.tags: \"test\"",
  "action": "enable"
}
响应代码edit
200
表示成功调用。
响应负载edit

对于 enable、disable、delete、edit 和 duplicate 操作，一个包含操作结果的 JSON 对象

  • attributes.summary.total：与批量操作匹配的规则总数
  • attributes.summary.succeeded：成功结果的数量（已启用、删除或更新的规则数量）
  • attributes.summary.failed：失败结果的数量
  • attributes.summary.skipped：由于各种原因而跳过的规则数量（将在下面解释）
  • attributes.results.created：在操作执行期间创建的规则对象
  • attributes.results.updated：在操作执行期间更新的规则对象
  • attributes.results.deleted：在操作执行期间删除的规则对象
  • attributes.results.skipped：在操作执行期间跳过的规则

仅当对规则执行的批量操作导致没有任何操作时，规则才会被 skipped。例如，如果 edit 操作用于向已具有该标签的规则添加标签，或者删除规则中未指定的索引模式。在 attributes.results.skipped 中返回的对象将只包含规则的 id、name 和 skip_reason。

{
   "success":true,
   "rules_count": 1,
   "attributes":{
      "results":{
         "updated":[
            {
               "id":"8bc7dad0-9320-11ec-9265-8b772383a08d",
               "updated_at":"2022-02-21T17:05:50.883Z",
               "updated_by":"elastic",
               "created_at":"2022-02-21T14:14:13.801Z",
               "created_by":"elastic",
               "name":"DNS Tunneling [Duplicate]",
               "tags":[
                  "Elastic",
                  "Network",
                  "Threat Detection",
                  "ML"
               ],
               "interval":"15m",
               "enabled":true,
               "description":"A machine learning job detected unusually large numbers of DNS queries for a single top-level DNS domain, which is often used for DNS tunneling. DNS tunneling can be used for command-and-control, persistence, or data exfiltration activity. For example, dnscat tends to generate many DNS questions for a top-level domain as it uses the DNS protocol to tunnel data.",
               "risk_score":21,
               "severity":"low",
               "license":"Elastic License v2",
               "author":[
                  "Elastic"
               ],
               "false_positives":[
                  "DNS domains that use large numbers of child domains, such as software or content distribution networks, can trigger this alert and such parent domains can be excluded."
               ],
               "from":"now-45m",
               "rule_id":"7289bf08-4e91-4c70-bf01-e04c4c5d7756",
               "max_signals":100,
               "risk_score_mapping":[

               ],
               "severity_mapping":[

               ],
               "threat":[

               ],
               "to":"now",
               "references":[
                  "https://elastic.ac.cn/guide/en/security/current/prebuilt-ml-jobs.html"
               ],
               "version":6,
               "exceptions_list":[

               ],
               "immutable":false,
               "related_integrations": [],       
               "required_fields": [],            
               "setup": "",
               "type":"machine_learning",
               "anomaly_threshold":50,
               "machine_learning_job_id":[
                  "packetbeat_dns_tunneling"
               ],
               "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,
                   }
                 }
               }
            }
         ],
         "created":[

         ],
         "deleted":[

         ],
         "skipped":[
            { "id": "51658332-a15e-4c9e-912a-67214e2e2359", "name": "Skipped rule", "skip_reason": "RULE_NOT_MODIFIED" }
         ]
      },
      "summary":{
         "failed": 0,
         "skipped": 1,
         "succeeded": 1,
         "total": 2
      }
   }
}

[dev] 此功能尚处于开发阶段，可能会在将来的版本中发生更改或完全删除。这些功能不受支持，也不受官方 GA 功能支持 SLA 的约束。 这些字段正在开发中，其用法或架构可能会发生变化：related_integrations、required_fields 和 execution_summary。

对于 export 操作，一个包含导出的规则的 .ndjson 文件。

示例 2，部分失败

以下请求将标签 tag-1 和 tag-2 添加到负载中发送的 ID 的规则

POST api/detection_engine/rules/_bulk_action
{
  "ids":[
    "8bc7dad0-9320-11ec-9265-8b772383a08d",
    "8e5c1a40-9320-11ec-9265-8b772383a08d"
  ],
  "action": "edit",
  "edit": [{ "type": "add_tags", "value":["tag-1", "tag-2"] }]
}
响应代码edit
500
指示部分批量操作失败。
响应负载edit

如果处理任何规则失败，部分错误将输出受影响规则的 ID 和/或名称以及相应的错误，以及成功处理的规则（与成功的 200 请求格式相同）。

示例负载edit

{
    "message": "Bulk edit partially failed",
    "status_code": 500,
    "attributes": {
        "errors": [
            {
                "message": "Index patterns can't be added. Machine learning rule doesn't have index patterns property",
                "status_code": 500,
                "rules": [
                    {
                        "id": "8bc7dad0-9320-11ec-9265-8b772383a08d",
                        "name": "DNS Tunneling [Duplicate]"
                    }
                ]
            }
        ],
        "results": {
            "updated": [
                {
                    "id": "8e5c1a40-9320-11ec-9265-8b772383a08d",
                    "updated_at": "2022-02-21T16:56:22.818Z",
                    "updated_by": "elastic",
                    "created_at": "2022-02-21T14:14:17.883Z",
                    "created_by": "elastic",
                    "name": "External Alerts [Duplicate]",
                    "tags": [
                        "Elastic",
                        "Network",
                        "Windows",
                        "APM",
                        "macOS",
                        "Linux"
                    ],
                    "interval": "5m",
                    "enabled": true,
                    "description": "Generates a detection alert for each external alert written to the configured indices. Enabling this rule allows you to immediately begin investigating external alerts in the app.",
                    "risk_score": 47,
                    "severity": "medium",
                    "license": "Elastic License v2",
                    "rule_name_override": "message",
                    "timestamp_override": "event.ingested",
                    "author": [
                        "Elastic"
                    ],
                    "false_positives": [],
                    "from": "now-6m",
                    "rule_id": "941faf98-0cdc-4569-b16d-4af962914d61",
                    "max_signals": 10000,
                    "risk_score_mapping": [
                        {
                            "field": "event.risk_score",
                            "value": "",
                            "operator": "equals"
                        }
                    ],
                    "severity_mapping": [
                        {
                            "severity": "low",
                            "field": "event.severity",
                            "value": "21",
                            "operator": "equals"
                        },
                        {
                            "severity": "medium",
                            "field": "event.severity",
                            "value": "47",
                            "operator": "equals"
                        },
                        {
                            "severity": "high",
                            "field": "event.severity",
                            "value": "73",
                            "operator": "equals"
                        },
                        {
                            "severity": "critical",
                            "field": "event.severity",
                            "value": "99",
                            "operator": "equals"
                        }
                    ],
                    "threat": [],
                    "to": "now",
                    "references": [],
                    "version": 5,
                    "exceptions_list": [],
                    "immutable": false,
                    "related_integrations": [],       
                    "required_fields": [],            
                    "setup": "",
                    "type": "query",
                    "language": "kuery",
                    "index": [
                        "apm-*-transaction*",
                        "traces-apm*",
                        "auditbeat-*",
                        "filebeat-*",
                        "logs-*",
                        "packetbeat-*",
                        "winlogbeat-*",
                        "added-by-id-*"
                    ],
                    "query": "event.kind:alert and not event.module:(endgame or endpoint)\n",
                    "actions": [],
                    "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,
                      }
                    }
                  }
                }
            ],
            "created": [],
            "deleted": [],
            "skipped": [],
        },
        "summary": {
            "failed": 1,
            "succeeded": 1,
            "skipped": 0,
            "total": 2
        }
    }
}

[dev] 此功能尚处于开发阶段，可能会在将来的版本中发生更改或完全删除。这些功能不受支持，也不受官方 GA 功能支持 SLA 的约束。 这些字段正在开发中，其用法或架构可能会发生变化：related_integrations、required_fields 和 execution_summary。

示例 3，模拟运行

以下请求将验证 add_index_patterns 批量操作是否可以成功应用于三条规则。每条规则（由其规则 ID 指定）都不同：一条是预先构建的 Elastic 规则，另一条是自定义机器学习规则，另一条是自定义查询规则。由于启用了模拟运行模式，因此对这些规则的更改不会是永久性的，也不会保存到 Elasticsearch。

POST api/detection_engine/rules/_bulk_action?dry_run=true
{
    "action": "edit",
    "edit": [
        {
            "value": [
                "test-*"
            ],
            "type": "add_index_patterns"
        }
    ],
    "ids": ["81aa0480-06af-11ed-94fb-dd1a0597d8d2", "dc015d10-0831-11ed-ac8b-05a222bd8d4a", "de8f5af0-0831-11ed-ac8b-05a222bd8d4a"]
}
响应代码edit
500
指示部分批量操作失败。
响应负载edit

响应的 attributes.errors 部分显示两条规则更新失败，一条规则更新成功。如果您在未启用模拟运行模式的情况下运行请求，将会返回相同的结果。请注意，attributes.results 中没有数组。在模拟运行模式下，规则更新不会应用到 Elasticsearch 也不会保存到 Elasticsearch，因此端点不会返回已 updated、created 或 deleted 规则的结果。

响应正文edit
{
    "message": "Bulk edit partially failed",
    "status_code": 500,
    "attributes": {
        "errors": [
            {
                "message": "Elastic rule can't be edited",
                "status_code": 500,
                "err_code": "IMMUTABLE",
                "rules": [
                    {
                        "id": "81aa0480-06af-11ed-94fb-dd1a0597d8d2",
                        "name": "Unusual AWS Command for a User"
                    }
                ]
            },
            {
                "message": "Machine learning rule doesn't have index patterns",
                "status_code": 500,
                "err_code": "MACHINE_LEARNING_INDEX_PATTERN",
                "rules": [
                    {
                        "id": "dc015d10-0831-11ed-ac8b-05a222bd8d4a",
                        "name": "Suspicious Powershell Script [Duplicate]"
                    }
                ]
            }
        ],
        "results": {
            "updated": [],
            "created": [],
            "deleted": [],
            "skipped": [],
        },
        "summary": {
            "failed": 2,
            "succeeded": 1,
            "skipped": 0,
            "total": 3
        }
    }
}
« 删除规则 索引端点 »