Link Search Menu Expand Document Documentation Menu
文档

检测器 API

以下 API 可用于执行与检测器相关的多种任务，包括创建、更新和搜索检测器。许多 API 调用在请求中使用了检测器 ID，该 ID 可以通过搜索检测器 API进行检索。

创建检测器 API

创建一个新的检测器。

POST _plugins/_security_analytics/detectors

请求正文字段

创建检测器时可以指定以下字段。

字段 类型 描述
enabled 布尔型 将检测器设置为活动（true）或非活动（false）。创建新检测器时，默认值为true。必填。
名称 字符串 检测器名称。名称只能包含大小写字母、数字 0-9、连字符、空格和下划线。使用 5 到 50 个字符。必填。
detector_type 字符串 定义检测器的日志类型。选项包括linux、network、windows、ad_ldap、apache_access、cloudtrail、dns 和 s3。必填。
schedule 对象 确定检测器运行频率的计划。有关在 API 中指定固定间隔的信息，请参阅Cron 表达式参考。
schedule.period 对象 计划频率的详细信息。
schedule.period.interval 整数 检测器运行的间隔。
schedule.period.unit 字符串 间隔的时间单位。
inputs 对象 检测器输入。
inputs.detector_input 数组 一个包含用于创建检测器的索引和定义的数组。目前，检测器只允许一个日志数据源。
inputs.detector_input.description 字符串 检测器的描述。可选。
inputs.detector_input.custom_rules 数组 自定义规则的检测器输入。检测器必须指定至少一个规则。如果指定了预打包规则，则此项可选。
inputs.detector_input.custom_rules.id 字符串 用户生成的自定义规则的有效规则 ID。有效规则的格式为全局唯一标识符（UUID）。有关更多信息，请参阅通用唯一标识符。
inputs.detector_input.indices 数组 用于检测器的日志数据源，可以是索引名称或索引模式。目前只支持一个条目，未来版本计划支持多个索引。必填。
inputs.detector_input.pre_packaged_rules 数组 预打包规则（与自定义规则相对）的检测器输入。检测器必须指定至少一个规则。如果指定了自定义规则，则此项可选。
inputs.detector_input.pre_packaged_rules.id 字符串 预打包规则的规则 ID。有关如何使用 API 搜索规则并在结果中获取规则 ID 的信息，请参阅搜索预打包规则。
triggers 数组 告警的触发器设置。
triggers.ids 数组 构成触发器条件一部分的规则 ID 列表。
triggers.tags 数组 标签在安全规则中指定。然后可以选择标签并将其应用于告警触发器，以集中告警的触发器条件。有关标签如何在 Sigma 规则中使用的示例，请参阅 Sigma 的规则创建指南。
triggers.id 字符串 触发器的唯一 ID。
triggers.sev_levels 数组 Sigma 规则严重性级别：informational（信息）；low（低）；medium（中）；high（高）；criticial（危急）。请参阅 Sigma 规则创建指南中的级别。
triggers.name 字符串 触发器名称。名称只能包含大小写字母、数字 0-9、连字符、空格和下划线。使用 5 到 50 个字符。必填。
triggers.severity 整数 触发器的严重性级别，表示为整数：1 = 最高；2 = 高；3 = 中；4 = 低；5 = 最低。触发器严重性是告警定义的一部分。
triggers.actions 对象 当满足触发器条件时，操作会发送通知。可选，因为告警中不强制要求通知消息。
triggers.actions.id 字符串 操作的唯一 ID。用户生成。
triggers.actions.destination_id 字符串 通知目的地的唯一 ID。用户生成。
triggers.actions.subject_template 对象 包含通知消息主题字段的信息。可选。
triggers.actions.subject_template.source 字符串 通知消息的主题。
triggers.actions.subject_template.lang 字符串 用于定义主题的脚本语言。必须是 Mustache。有关模板的更多信息，请参阅Mustache 手册。
triggers.actions.name 字符串 触发器告警的名称。名称只能包含大小写字母、数字 0-9、连字符、空格和下划线。使用 5 到 50 个字符。
triggers.actions.message_template 字符串 包含通知消息正文的信息。可选。
triggers.actions.message_template.source 字符串 通知消息的正文。
triggers.actions.message_template.lang 字符串 用于定义消息的脚本语言。必须是Mustache。
triggers.actions.throttle_enabled 布尔型 启用告警通知的节流。可选。默认值为false。
triggers.actions.throttle 对象 节流限制了您在给定时间段内收到的通知数量。
triggers.actions.throttle.unit 字符串 节流的时间单位。
triggers.actions.throttle.value 整数 时间单位的值。

请求示例

POST _plugins/_security_analytics/detectors
{
  "enabled": true,
  "schedule": {
    "period": {
      "interval": 1,
      "unit": "MINUTES"
    }
  },
  "detector_type": "WINDOWS",
  "type": "detector",
  "inputs": [
    {
      "detector_input": {
        "description": "windows detector for security analytics",
        "custom_rules": [
          {
            "id": "bc2RB4QBrbtylUb_1Pbm"
          }
        ],
        "indices": [
          "windows"
        ],
        "pre_packaged_rules": [
          {
            "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "ids": [
        "06724a9a-52fc-11ed-bdc3-0242ac120002"
      ],
      "types": [],
      "tags": [
        "attack.defense_evasion"
      ],
      "severity": "1",
      "actions": [{
          "id": "hVTLkZYzlA",
          "destination_id": "6r8ZBoQBKW_6dKriacQb",
          "subject_template": {
            "source": "Trigger: ",
            "lang": "mustache"
          },
          "name": "hello_world",
          "throttle_enabled": false,
          "message_template": {
            "source": "Detector  just entered alert status. Please investigate the issue." +
            "- Trigger: " +
            "- Severity: ",
            "lang": "mustache"
          },
          "throttle": {
            "unit": "MINUTES",
            "value": 108
          }
        }
      ],
      "id": "8qhrBoQBYK1JzUUDzH-N",
      "sev_levels": [],
      "name": "test-trigger"
    }
  ],
  "name": "nbReFCjlfn"
}

示例响应

{
    "_id": "dc2VB4QBrbtylUb_Hfa3",
    "_version": 1,
    "detector": {
        "name": "nbReFCjlfn",
        "detector_type": "windows",
        "enabled": true,
        "schedule": {
            "period": {
                "interval": 1,
                "unit": "MINUTES"
            }
        },
        "inputs": [
            {
                "detector_input": {
                    "description": "windows detector for security analytics",
                    "indices": [
                        "windows"
                    ],
                    "custom_rules": [
                        {
                            "id": "bc2RB4QBrbtylUb_1Pbm"
                        }
                    ],
                    "pre_packaged_rules": [
                        {
                            "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
                        }
                    ]
                }
            }
        ],
        "triggers": [
            {
                "id": "8qhrBoQBYK1JzUUDzH-N",
                "name": "test-trigger",
                "severity": "1",
                "types": [],
                "ids": [
                    "06724a9a-52fc-11ed-bdc3-0242ac120002"
                ],
                "sev_levels": [],
                "tags": [
                    "attack.defense_evasion"
                ],
                "actions": [
                    {
                        "id": "hVTLkZYzlA",
                        "name": "hello_world",
                        "destination_id": "6r8ZBoQBKW_6dKriacQb",
                        "message_template": {
                            "source": "Trigger: ",
                            "lang": "mustache"
                        },
                        "throttle_enabled": false,
                        "subject_template": {
                            "source": "Detector  just entered alert status. Please investigate the issue." +
                    "- Trigger: " +
                    "- Severity: ",
                            "lang": "mustache"
                        },
                        "throttle": {
                            "value": 108,
                            "unit": "MINUTES"
                        }
                    }
                ]
            }
        ],
        "last_update_time": "2022-10-24T01:22:03.738379671Z",
        "enabled_time": "2022-10-24T01:22:03.738376103Z"
    }
}

更新检测器 API

更新检测器 API 可用于更新检测器定义。它需要检测器 ID 来指定检测器。

PUT /_plugins/_security_analytics/detectors/<detector_Id>

请求正文字段

更新检测器时可以指定以下字段。

字段 类型 描述
detector_type 字符串 定义检测器的日志类型。选项包括linux、network、windows、ad_ldap、apache_access、cloudtrail、dns 和 s3。
名称 字符串 检测器名称。名称只能包含大小写字母、数字 0-9、连字符、空格和下划线。使用 5 到 50 个字符。必填。
enabled 布尔型 将检测器设置为活动（true）或非活动（false）。
schedule.period.interval 整数 检测器运行的间隔。
schedule.period.unit 字符串 间隔的时间单位。
inputs.input.description 字符串 检测器的描述。
inputs.input.indices 数组 用于检测器的日志数据源。目前只允许一个源。
inputs.input.rules.id 数组 检测器定义的安全规则列表。
triggers.sev_levels 数组 Sigma 规则严重性级别：informational（信息）；low（低）；medium（中）；high（高）；criticial（危急）。请参阅 Sigma 规则创建指南中的级别。
triggers.tags 数组 标签在安全规则中指定。然后可以选择标签并将其应用于告警触发器，以集中告警的触发器条件。有关标签如何在 Sigma 规则中使用的示例，请参阅 Sigma 的规则创建指南。
triggers.actions 对象 当满足触发器条件时，操作会发送通知。请参阅创建检测器 API 的触发器操作。

请求示例

PUT /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR
{
  "type": "detector",
  "detector_type": "windows",
  "name": "windows_detector",
  "enabled": true,
  "createdBy": "chip",
  "schedule": {
    "period": {
      "interval": 1,
      "unit": "MINUTES"
    }
  },
  "inputs": [
    {
      "input": {
        "description": "windows detector for security analytics",
        "indices": [
          "windows"
        ],
        "custom_rules": [],
        "pre_packaged_rules": [
          {
            "id": "73a883d0-0348-4be4-a8d8-51031c2564f8"
          },
          {
            "id": "1a4bd6e3-4c6e-405d-a9a3-53a116e341d4"
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "sev_levels": [],
      "tags": [],
      "actions": [],
      "types": [
        "windows"
      ],
      "name": "test-trigger",
      "id": "fyAy1IMBK2A1DZyOuW_b"
    }
  ]
}

示例响应

{
    "_id": "J1RX1IMByX0LvTiGTddR",
    "_version": 1,
    "detector": {
        "name": "windows_detector",
        "detector_type": "windows",
        "enabled": true,
        "schedule": {
            "period": {
                "interval": 1,
                "unit": "MINUTES"
            }
        },
        "inputs": [
            {
                "detector_input": {
                    "description": "windows detector for security analytics",
                    "indices": [
                        "windows"
                    ],
                    "rules": [
                        {
                            "id": "LFRY1IMByX0LvTiGZtfh"
                        }
                    ]
                }
            }
        ],
        "triggers": [],
        "last_update_time": "2022-10-14T02:36:32.909581688Z",
        "enabled_time": "2022-10-14T02:33:34.197Z"
    }
}

响应正文字段

字段 类型 描述
_version 字符串 更新的版本号。
detector.last_update_time 字符串 上次更新的日期和时间。
detector.enabled_time 字符串 检测器上次启用时的日期和时间。

删除检测器 API

此 API 使用检测器 ID 来指定和删除检测器。

端点

DELETE /_plugins/_security_analytics/detectors/IJAXz4QBrmVplM4JYxx_

请求示例

DELETE /_plugins/_security_analytics/detectors/<detector Id>

示例响应

{
  "_id" : "IJAXz4QBrmVplM4JYxx_",
  "_version" : 1
}

获取检测器 API

获取检测器 API 用于检索检测器详细信息。在调用中使用检测器 ID 来获取检测器详细信息。

端点

GET /_plugins/_security_analytics/detectors/x-dwFIYBT6_n8WeuQjo4

请求示例

GET /_plugins/_security_analytics/detectors/<detector Id>

示例响应

{
  "_id" : "x-dwFIYBT6_n8WeuQjo4",
  "_version" : 1,
  "detector" : {
    "name" : "DetectorTest1",
    "detector_type" : "windows",
    "enabled" : true,
    "schedule" : {
      "period" : {
        "interval" : 1,
        "unit" : "MINUTES"
      }
    },
    "inputs" : [
      {
        "detector_input" : {
          "description" : "Test and delete",
          "indices" : [
            "windows1"
          ],
          "custom_rules" : [ ],
          "pre_packaged_rules" : [
            {
              "id" : "847def9e-924d-4e90-b7c4-5f581395a2b4"
            }
          ]
        }
      }
    ],
    "last_update_time" : "2023-02-02T23:22:26.454Z",
    "enabled_time" : "2023-02-02T23:22:26.454Z"
  }
}

搜索检测器 API

搜索检测器 API 通过检测器 ID、检测器名称或检测器类型搜索检测器匹配项。

请求正文字段

字段 类型 描述
_id 字符串 更新的版本号。
detector.name 字符串 检测器的名称。
detector_type 字符串 检测器的日志类型。选项包括 linux, network ,windows, ad_ldap, apache_access, cloudtrail, dns, and s3。

请求示例

检测器 ID

POST /_plugins/_security_analytics/detectors/_search
{
    "query": {
        "match": {
            "_id": "MFRg1IMByX0LvTiGHtcN"
        }
    }
}

检测器名称

POST /_plugins/_security_analytics/detectors/_search
{
  "size": 30,  
  "query": {
    "nested": {
      "path": "detector",
      "query": {
        "bool": {
          "must": [
            { "match": {"detector.name": "DetectorTest1"} }
          ]
        }
      }
    }
  }
}

示例响应

{
  "took" : 0,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 3.671739,
    "hits" : [
      {
        "_index" : ".opensearch-sap-detectors-config",
        "_id" : "x-dwFIYBT6_n8WeuQjo4",
        "_version" : 1,
        "_seq_no" : 76,
        "_primary_term" : 17,
        "_score" : 3.671739,
        "_source" : {
          "type" : "detector",
          "name" : "DetectorTest1",
          "detector_type" : "windows",
          "enabled" : true,
          "enabled_time" : 1675380146454,
          "schedule" : {
            "period" : {
              "interval" : 1,
              "unit" : "MINUTES"
            }
          },
          "inputs" : [
            {
              "detector_input" : {
                "description" : "Test and delete",
                "indices" : [
                  "windows1"
                ],
                "custom_rules" : [ ],
                "pre_packaged_rules" : [
                  {
                    "id" : "847def9e-924d-4e90-b7c4-5f581395a2b4"
                  }
                ]
              }
            }
          ],
          "triggers" : [
            {
              "id" : "w-dwFIYBT6_n8WeuQToW",
              "name" : "trigger 1",
              "severity" : "1",
              "types" : [
                "windows"
              ],
              "ids" : [
                "847def9e-924d-4e90-b7c4-5f581395a2b4"
              ],
              "sev_levels" : [
                "critical"
              ],
              "tags" : [
                "attack.t1003.002"
              ],
              "actions" : [
                {
                  "id" : "",
                  "name" : "Triggered alert condition:  - Severity: 1 (Highest) - Threat detector: DetectorTest1",
                  "destination_id" : "",
                  "message_template" : {
                    "source" : """Triggered alert condition: 
Severity: 1 (Highest)
Threat detector: DetectorTest1
Description: Test and delete
Detector data sources:
  windows1""",
                    "lang" : "mustache"
                  },
                  "throttle_enabled" : false,
                  "subject_template" : {
                    "source" : "Triggered alert condition:  - Severity: 1 (Highest) - Threat detector: DetectorTest1",
                    "lang" : "mustache"
                  },
                  "throttle" : {
                    "value" : 10,
                    "unit" : "MINUTES"
                  }
                }
              ]
            }
          ],
          "last_update_time" : 1675380146454,
          "monitor_id" : [
            "xOdwFIYBT6_n8WeuQToa"
          ],
          "bucket_monitor_id_rule_id" : {
            "-1" : "xOdwFIYBT6_n8WeuQToa"
          },
          "rule_topic_index" : ".opensearch-sap-windows-detectors-queries",
          "alert_index" : ".opensearch-sap-windows-alerts",
          "alert_history_index" : ".opensearch-sap-windows-alerts-history",
          "alert_history_index_pattern" : "<.opensearch-sap-windows-alerts-history-{now/d}-1>",
          "findings_index" : ".opensearch-sap-windows-findings",
          "findings_index_pattern" : "<.opensearch-sap-windows-findings-{now/d}-1>"
        }
      }
    ]
  }
}
剩余 350 字符

有问题？。

想贡献？ 或 。