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: 指示调用成功。

响应有效载荷

编辑

包含每个规则的唯一 ID 的 JSON 数组。为所有不包含 rule_id 字段的规则生成唯一的规则 ID。

批量删除

编辑

此 API 自 8.2 版本起已弃用，计划于 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 数组。

批量更新

编辑

此 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` `编辑` `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: String[] }	向规则添加自定义突出显示的字段
`delete_investigation_fields`	{ field_names: String[] }	删除规则的自定义突出显示字段
`set_investigation_fields`	{ field_names: String[] }	覆盖规则的自定义突出显示字段
`add_index_patterns`	字符串[]	向规则添加索引模式
`delete_index_patterns`	字符串[]	删除规则的索引模式
`set_index_patterns`	字符串[]	覆盖规则的索引模式
`set_timeline`	{ `timeline_id`: String; `timeline_title`: String }	覆盖规则的时间线模板
`set_schedule`	{ `interval`: String; `lookback`: String }	覆盖规则的计划 `interval`：规则执行的频率。例如，`"1h"` 表示规则每小时运行一次。 `lookback`：规则分析的其他回溯时间。例如，`"10m"` 表示规则除了频率间隔外，还会分析过去 10 分钟的数据。如果 `interval` 设置为 `"10m"` 且 `lookback` 设置为 `"1m"`，则规则每 5 分钟运行一次，但会分析过去 11 分钟添加到索引的文档。 `interval` 和 `lookback` 的格式均为 `"{整数}{时间单位}"`，其中接受的时间单位是秒（`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` (字符串，可选)：事件的摘要。默认为 `未提供摘要`。最大长度为 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
      }
   }
}

[dev] 此功能正在开发中，可能会在未来的版本中更改或完全删除。这些功能不受支持，也不受官方 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
        }
    }
}

« 删除规则索引端点 »

批量规则操作