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。

批量删除

编辑

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

删除多个规则。

请求 URL

编辑

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

请求正文

编辑

要删除的规则的 id 或 rule_id 字段的 JSON 数组。

示例请求

编辑

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 数组。

批量更新

编辑

自 8.2 版起，此 API 已弃用，并计划于 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` `编辑` `run`	是
`run`	BulkManualRuleRun[]	描述应用手动规则运行操作的对象。	否。是，如果 action 为 `run`。
`编辑`	BulkEditAction[]	描述应用更新操作的编辑对象。	否。是，如果 action 为 `edit`。
`duplicate`	BulkDuplicateAction[]	描述应用更新操作的复制对象。	否。

试运行模式

编辑

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

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

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

BulkManualRuleRun 对象

编辑

start_date 字段：（字符串，必需）定义手动运行的开始日期。
end_date 字段：（字符串，可选）定义手动运行的结束日期。

BulkDuplicateAction 对象

编辑

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

BulkEditAction 对象

编辑

type 字段：枚举。定义将在规则中更新的内容。
value 字段：任何。将在编辑操作中应用的值。

可能的 `BulkEditAction` 对象值

编辑

`type` 字段	`value` 字段	描述
`add_tags`	字符串[]	向规则添加标签
`delete_tags`	字符串[]	删除规则的标签
`set_tags`	字符串[]	覆盖规则的标签
`add_investigation_fields`	{ field_names: 字符串[] }	向规则添加自定义突出显示字段
`delete_investigation_fields`	{ field_names: 字符串[] }	删除规则的自定义突出显示字段
`set_investigation_fields`	{ field_names: 字符串[] }	覆盖规则的自定义突出显示字段
`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`（日期时间，可选）：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`（对象，必填）：此操作可以运行的一天中的小时。一天中的小时以 `hh:mm` 格式和 24 小时制表示为两个字符串。`00:00` 的开始和 `24:00` 的结束表示操作可以全天运行。要设置隔夜时间范围，请指定一个早于或等于 `start` 时间的 `end` 时间。例如：`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` 模式

编辑

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

规则级别的 throttle 字段在 Elastic Security 8.8 中已弃用，并计划于 2024 年第四季度停止使用。

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

"rule"：在每次规则执行时执行操作
"1h"：每小时执行一次操作
"1d"：每天执行一次操作
"7d"：每周执行一次操作

示例请求

编辑

示例 1

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

POST api/detection_engine/rules/_bulk_action
{
  "query": "alert.attributes.tags: \"test\"",
  "action": "enable"
}

响应代码

编辑

200: 表示成功调用。

响应有效负载

编辑

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

attributes.summary.total：与批量操作匹配的规则总数
attributes.summary.succeeded：成功结果的数量（已启用、删除或更新的规则数量）
attributes.summary.failed：失败结果的数量
attributes.summary.skipped：由于各种原因而跳过的规则数量（如下所述）
attributes.results.created：在操作执行期间创建的规则对象
attributes.results.updated：在操作执行期间更新的规则对象。如果操作执行为 run，则返回已计划手动运行的规则对象。
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
      }
   }
}

[开发中] 此功能正在开发中，可能会在将来的版本中更改或完全删除。这些功能不受支持，并且不受官方 GA 功能的支持 SLA 的约束。这些字段正在开发中，其用法或模式可能会更改：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"] }]
}

响应代码

编辑

500: 指示批量操作部分失败。

响应有效负载

编辑

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

示例有效负载

编辑

{
    "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
        }
    }
}

示例 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"]
}

响应代码

编辑

500: 指示批量操作部分失败。

响应有效负载

编辑

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

响应正文

编辑

{
    "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
        }
    }
}

« 删除规则索引端点 »

批量规则操作