Link Search Menu Expand Document Documentation Menu
Documentation

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.

Create Detector API

Creates a new detector.

POST _plugins/_security_analytics/detectors

Request body 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.
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 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 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.
triggers.id String The unique ID for the trigger.
triggers.sev_levels Array Sigma rule severity levels: informational; low; medium; high; criticial. See 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 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

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

Example response

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

Update Detector API

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

PUT /_plugins/_security_analytics/detectors/<detector_Id>

Request body 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 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.
triggers.actions Object Actions send notifications when trigger conditions are met. See trigger actions for Create Detector API.

Example request

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

Example response

{
    "_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 body 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

DELETE /_plugins/_security_analytics/detectors/IJAXz4QBrmVplM4JYxx_

Example request

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

Example response

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

GET /_plugins/_security_analytics/detectors/x-dwFIYBT6_n8WeuQjo4

Example request

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

Example response

{
  "_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 body 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

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

Detector name

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

Example response

{
  "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 characters left

Have a question? .

Want to contribute? or .