opensearch-docs-cn/_security-analytics/api-tools/detector-api.md

---
layout: default
title: Detector APIs
parent: API tools
nav_order: 35
---

# Detector APIs

The following APIs can be used for a number of tasks related to detectors, from creating detectors to updating and searching for detectors. Many API calls use the detector ID in the request, which can be retrieved using the [Search Detector API](#search-detector-api).

## Create Detector API

Creates a new detector.

```json
POST _plugins/_security_analytics/detectors
```

### Request fields

You can specify the following fields when creating a detector.

Field | Type | Description
:--- | :--- |:--- |
`enabled` | Boolean | Sets the detector as either active (true) or inactive (false). Default is `true` when a new detector is created. Required.
`name` | String | Name of the detector. Name should only consist of upper and lowercase letters, numbers 0-9, hyphens, spaces, and underscores. Use between 5 and 50 characters. Required.
`detector_type` | String | The log type that defines the detector. Options are `linux`, `network` ,`windows`, `ad_ldap`, `apache_access`, `cloudtrail`, `dns`, and `s3`. Required.
`schedule` | Object | The schedule that determines how often the detector runs. For information about specifying fixed intervals in the API, see the [Cron expression reference]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/).
`schedule.period` | Object | Details for the frequency of the schedule.
`schedule.period.interval` | Integer | The interval at which the detector runs.
`schedule.period.unit` | String | The interval's unit of time.
`inputs` | Object | Detector inputs.
`inputs.detector_input` | Array | An array that contains the index and definition used to create the detector. Currently, only one log data source is allowed for the detector.
`inputs.detector_input.description` | String | Description of the detector. Optional.
`inputs.detector_input.custom_rules` | Array | Detector inputs for custom rules. At least one rule must be specified for a detector. Optional if pre-packaged rules are specified.
`inputs.detector_input.custom_rules.id` | String | A valid rule ID for the custom rule generated by the user. Valid rules are formatted as a globally, or, universally unique identifier (UUID) See [Universally unique identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) for more information.
`inputs.detector_input.indices` | Array | The log data source used for the detector, which can be either an index name or index pattern. Currently, only one entry is supported with plans to support multiple indexes in a future release. Required.
`inputs.detector_input.pre_packaged_rules` | Array | Detector inputs for pre-packaged rules (as opposed to custom rules). At least one rule must be specified for a detector. Optional if custom rules are specified.
`inputs.detector_input.pre_packaged_rules.id` | String | The rule ID for pre-packaged rules. See [Search Pre-Packaged Rules]({{site.url}}{{site.baseurl}}/security-analytics/api-tools/rule-api/#search-pre-packaged-rules) for information on how to use the API to search for rules and obtain rule IDs in results.
`triggers` | Array | Trigger settings for alerts.
`triggers.ids` | Array | A list of rule IDs that become part of the trigger condition.
`triggers.tags` | Array | Tags are specified in a security rule. Tags can then be selected and applied to the alert trigger to focus the trigger conditions for alerts. See an example of how tags are used in a Sigma rule in Sigma's [Rule Creation Guide](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#tags).
`triggers.id` | String | The unique ID for the trigger.
`triggers.sev_levels` | Array | Sigma rule severity levels: `informational`; `low`; `medium`; `high`; `criticial`. See [Level](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#level) in the Sigma Rule Creation Guide.
`triggers.name` | String | The name of the trigger. Name should only consist of upper and lowercase letters, numbers 0-9, hyphens, spaces, and underscores. Use between 5 and 50 characters. Required.
`triggers.severity` | Integer | Severity level for the trigger expressed as an integer: 1 = highest; 2 = high; 3 = medium; 4 = low; 5 = lowest. Trigger severity is part of the alert definition.
`triggers.actions` | Object | Actions send notifications when trigger conditions are met. Optional, as a notification message is not required as part of an alert.
`triggers.actions.id` | String | Unique ID for the action. User generated.
`triggers.actions.destination_id` | String | Unique ID for the notification destination. User generated. 
`triggers.actions.subject_template` | Object | Contains the information for the subject field of the notification message. Optional.
`triggers.actions.subject_template.source` | String | The subject for the notification message.
`triggers.actions.subject_template.lang` | String | The scripting language used to define the subject. Must be Mustache. See the [Mustache Manual](https://mustache.github.io/mustache.5.html) for more information about templates.
`triggers.actions.name` | String | Name for the trigger alert. Name should only consist of upper and lowercase letters, numbers 0-9, hyphens, spaces, and underscores. Use between 5 and 50 characters.
`triggers.actions.message_template` | String | Contains the information for the body of the notification message. Optional.
`triggers.actions.message_template.source` | String | The body of the notification message.
`triggers.actions.message_template.lang` | String | The scripting language used to define the message. Must be `Mustache`.
`triggers.actions.throttle_enabled` | Boolean | Enables throttling for alert notifications. Optional. Default is `false`.
`triggers.actions.throttle` | Object | Throttling limits the number of notifications you receive within a given span of time.
`triggers.actions.throttle.unit` | String | Unit of time for throttling.
`triggers.actions.throttle.value` | Integer | The value for the unit of time.

### Example request

```json
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: {{ctx.trigger.name}}",
            "lang": "mustache"
          },
          "name": "hello_world",
          "throttle_enabled": false,
          "message_template": {
            "source": "Detector {{ctx.detector.name}} just entered alert status. Please investigate the issue." +
            "- Trigger: {{ctx.trigger.name}}" +
            "- Severity: {{ctx.trigger.severity}}",
            "lang": "mustache"
          },
          "throttle": {
            "unit": "MINUTES",
            "value": 108
          }
        }
      ],
      "id": "8qhrBoQBYK1JzUUDzH-N",
      "sev_levels": [],
      "name": "test-trigger"
    }
  ],
  "name": "nbReFCjlfn"
}
```
{% include copy-curl.html %}

### Example response

```json
{
    "_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: {{ctx.trigger.name}}",
                            "lang": "mustache"
                        },
                        "throttle_enabled": false,
                        "subject_template": {
                            "source": "Detector {{ctx.detector.name}} just entered alert status. Please investigate the issue." +
                    "- Trigger: {{ctx.trigger.name}}" +
                    "- Severity: {{ctx.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"
    }
}
```

---
## Update Detector API

The Update Detector API can be used to update a detector definition. It requires the detector ID to specify the detector.

```json
PUT /_plugins/_security_analytics/detectors/<detector_Id>
```

### Request fields

You can specify the following fields when updating a detector.

Field | Type | Description
:--- | :--- |:--- |
`detector_type` | String | The log type that defines the detector. Options are `linux`, `network` ,`windows`, `ad_ldap`, `apache_access`, `cloudtrail`, `dns`, and `s3`.
`name` | String | The name of the detector. Name should only consist of upper and lowercase letters, numbers 0-9, hyphens, spaces, and underscores. Use between 5 and 50 characters. Required.
`enabled` | Boolean | Sets the detector as either Active (true) or Inactive (false).
`schedule.period.interval` | Integer | The interval at which the detector runs.
`schedule.period.unit` | String | The interval's unit of time.
`inputs.input.description` | String | Description of the detector.
`inputs.input.indices` | Array | The log data source used for the detector. Only one source is allowed at this time.
`inputs.input.rules.id` | Array | A list of security rules for the detector definition.
`triggers.sev_levels` | Array | Sigma rule severity levels: `informational`; `low`; `medium`; `high`; `criticial`. See [Level](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#level) in the Sigma Rule Creation Guide.
`triggers.tags` | Array | Tags are specified in a security rule. Tags can then be selected and applied to the alert trigger to focus the trigger conditions for alerts. See an example of how tags are used in a Sigma rule in Sigma's [Rule Creation Guide](https://github.com/SigmaHQ/sigma/wiki/Rule-Creation-Guide#tags).
`triggers.actions` | Object | Actions send notifications when trigger conditions are met. See trigger actions for [Create Detector API]({{site.url}}{{site.baseurl}}/security-analytics/api-tools/detector-api/#create-detector-api).


### Example request

```json
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"
    }
  ]
}
```
{% include copy-curl.html %}

### Example response

```json
{
    "_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"
    }
}
```

#### Response fields

Field | Type | Description
:--- | :--- |:--- |
`_version` | String | Version number for the update.
`detector.last_update_time` | String | Date and time of the last update.
`detector.enabled_time` | String | Date and time when the detector was last enabled.

---
## Delete Detector API

This API uses the detector ID to specify and delete a detector.

### Path and HTTP methods

```json
DELETE /_plugins/_security_analytics/detectors/IJAXz4QBrmVplM4JYxx_
```

### Example request

```json
DELETE /_plugins/_security_analytics/detectors/<detector Id>
```
{% include copy-curl.html %}

### Example response

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

---
## Get Detector API

The Get Detector API retrieves the detector details. Use the detector ID in the call to fetch detector details.

### Path and HTTP methods

```json
GET /_plugins/_security_analytics/detectors/x-dwFIYBT6_n8WeuQjo4
```

### Example request

```json
GET /_plugins/_security_analytics/detectors/<detector Id>
```
{% include copy-curl.html %}

### Example response

```json
{
  "_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"
  }
}
```

---
## Search Detector API

The Search Detector API searches for detector matches by detector ID, detector name, or detector type.

### Request fields

Field | Type | Description
:--- | :--- |:--- |
`_id` | String | Version number for the update.
`detector.name` | String | Name of the detector.
`detector_type` | String | The log type for the detector. Options are `linux`, `network` ,`windows`, `ad_ldap`, `apache_access`, `cloudtrail`, `dns`, and `s3`.

### Example request

**Detector ID**
```json
POST /_plugins/_security_analytics/detectors/_search
{
    "query": {
        "match": {
            "_id": "MFRg1IMByX0LvTiGHtcN"
        }
    }
}
```
{% include copy-curl.html %}

**Detector name**
```json
POST /_plugins/_security_analytics/detectors/_search
{
  "size": 30,  
  "query": {
    "nested": {
      "path": "detector",
      "query": {
        "bool": {
          "must": [
            { "match": {"detector.name": "DetectorTest1"} }
          ]
        }
      }
    }
  }
}
```
{% include copy-curl.html %}

### Example response

```json
{
  "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>"
        }
      }
    ]
  }
}
```