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.

  1. POST _plugins/_security_analytics/detectors

Request body fields

You can specify the following fields when creating a detector.

FieldTypeDescription
enabledBooleanSets the detector as either active (true) or inactive (false). Default is true when a new detector is created. Required.
nameStringName 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_typeStringThe log type that defines the detector. Options are linux, network ,windows, ad_ldap, apache_access, cloudtrail, dns, and s3. Required.
scheduleObjectThe schedule that determines how often the detector runs. For information about specifying fixed intervals in the API, see the Cron expression reference.
schedule.periodObjectDetails for the frequency of the schedule.
schedule.period.intervalIntegerThe interval at which the detector runs.
schedule.period.unitStringThe interval’s unit of time.
inputsObjectDetector inputs.
inputs.detector_inputArrayAn 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.descriptionStringDescription of the detector. Optional.
inputs.detector_input.custom_rulesArrayDetector 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.idStringA 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.indicesArrayThe 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_rulesArrayDetector 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.idStringThe 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.
triggersArrayTrigger settings for alerts.
triggers.idsArrayA list of rule IDs that become part of the trigger condition.
triggers.tagsArrayTags 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.idStringThe unique ID for the trigger.
triggers.sev_levelsArraySigma rule severity levels: informational; low; medium; high; criticial. See Level in the Sigma Rule Creation Guide.
triggers.nameStringThe 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.severityIntegerSeverity 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.actionsObjectActions send notifications when trigger conditions are met. Optional, as a notification message is not required as part of an alert.
triggers.actions.idStringUnique ID for the action. User generated.
triggers.actions.destination_idStringUnique ID for the notification destination. User generated.
triggers.actions.subject_templateObjectContains the information for the subject field of the notification message. Optional.
triggers.actions.subject_template.sourceStringThe subject for the notification message.
triggers.actions.subject_template.langStringThe scripting language used to define the subject. Must be Mustache. See the Mustache Manual for more information about templates.
triggers.actions.nameStringName 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_templateStringContains the information for the body of the notification message. Optional.
triggers.actions.message_template.sourceStringThe body of the notification message.
triggers.actions.message_template.langStringThe scripting language used to define the message. Must be Mustache.
triggers.actions.throttle_enabledBooleanEnables throttling for alert notifications. Optional. Default is false.
triggers.actions.throttleObjectThrottling limits the number of notifications you receive within a given span of time.
triggers.actions.throttle.unitStringUnit of time for throttling.
triggers.actions.throttle.valueIntegerThe value for the unit of time.

Example request

  1. POST _plugins/_security_analytics/detectors
  2. {
  3.   "enabled": true,
  4.   "schedule": {
  5.     "period": {
  6.       "interval": 1,
  7.       "unit": "MINUTES"
  8.     }
  9.   },
  10.   "detector_type": "WINDOWS",
  11.   "type": "detector",
  12.   "inputs": [
  13.     {
  14.       "detector_input": {
  15.         "description": "windows detector for security analytics",
  16.         "custom_rules": [
  17.           {
  18.             "id": "bc2RB4QBrbtylUb_1Pbm"
  19.           }
  20.         ],
  21.         "indices": [
  22.           "windows"
  23.         ],
  24.         "pre_packaged_rules": [
  25.           {
  26.             "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
  27.           }
  28.         ]
  29.       }
  30.     }
  31.   ],
  32.   "triggers": [
  33.     {
  34.       "ids": [
  35.         "06724a9a-52fc-11ed-bdc3-0242ac120002"
  36.       ],
  37.       "types": [],
  38.       "tags": [
  39.         "attack.defense_evasion"
  40.       ],
  41.       "severity": "1",
  42.       "actions": [{
  43.           "id": "hVTLkZYzlA",
  44.           "destination_id": "6r8ZBoQBKW_6dKriacQb",
  45.           "subject_template": {
  46.             "source": "Trigger: ",
  47.             "lang": "mustache"
  48.           },
  49.           "name": "hello_world",
  50.           "throttle_enabled": false,
  51.           "message_template": {
  52.             "source": "Detector  just entered alert status. Please investigate the issue." +
  53.             "- Trigger: " +
  54.             "- Severity: ",
  55.             "lang": "mustache"
  56.           },
  57.           "throttle": {
  58.             "unit": "MINUTES",
  59.             "value": 108
  60.           }
  61.         }
  62.       ],
  63.       "id": "8qhrBoQBYK1JzUUDzH-N",
  64.       "sev_levels": [],
  65.       "name": "test-trigger"
  66.     }
  67.   ],
  68.   "name": "nbReFCjlfn"
  69. }

copy

Example response

  1. {
  2.     "_id": "dc2VB4QBrbtylUb_Hfa3",
  3.     "_version": 1,
  4.     "detector": {
  5.         "name": "nbReFCjlfn",
  6.         "detector_type": "windows",
  7.         "enabled": true,
  8.         "schedule": {
  9.             "period": {
  10.                 "interval": 1,
  11.                 "unit": "MINUTES"
  12.             }
  13.         },
  14.         "inputs": [
  15.             {
  16.                 "detector_input": {
  17.                     "description": "windows detector for security analytics",
  18.                     "indices": [
  19.                         "windows"
  20.                     ],
  21.                     "custom_rules": [
  22.                         {
  23.                             "id": "bc2RB4QBrbtylUb_1Pbm"
  24.                         }
  25.                     ],
  26.                     "pre_packaged_rules": [
  27.                         {
  28.                             "id": "06724a9a-52fc-11ed-bdc3-0242ac120002"
  29.                         }
  30.                     ]
  31.                 }
  32.             }
  33.         ],
  34.         "triggers": [
  35.             {
  36.                 "id": "8qhrBoQBYK1JzUUDzH-N",
  37.                 "name": "test-trigger",
  38.                 "severity": "1",
  39.                 "types": [],
  40.                 "ids": [
  41.                     "06724a9a-52fc-11ed-bdc3-0242ac120002"
  42.                 ],
  43.                 "sev_levels": [],
  44.                 "tags": [
  45.                     "attack.defense_evasion"
  46.                 ],
  47.                 "actions": [
  48.                     {
  49.                         "id": "hVTLkZYzlA",
  50.                         "name": "hello_world",
  51.                         "destination_id": "6r8ZBoQBKW_6dKriacQb",
  52.                         "message_template": {
  53.                             "source": "Trigger: ",
  54.                             "lang": "mustache"
  55.                         },
  56.                         "throttle_enabled": false,
  57.                         "subject_template": {
  58.                             "source": "Detector  just entered alert status. Please investigate the issue." +
  59.                     "- Trigger: " +
  60.                     "- Severity: ",
  61.                             "lang": "mustache"
  62.                         },
  63.                         "throttle": {
  64.                             "value": 108,
  65.                             "unit": "MINUTES"
  66.                         }
  67.                     }
  68.                 ]
  69.             }
  70.         ],
  71.         "last_update_time": "2022-10-24T01:22:03.738379671Z",
  72.         "enabled_time": "2022-10-24T01:22:03.738376103Z"
  73.     }
  74. }

Update Detector API

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

  1. PUT /_plugins/_security_analytics/detectors/<detector_Id>

Request body fields

You can specify the following fields when updating a detector.

FieldTypeDescription
detector_typeStringThe log type that defines the detector. Options are linux, network ,windows, ad_ldap, apache_access, cloudtrail, dns, and s3.
nameStringThe 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.
enabledBooleanSets the detector as either Active (true) or Inactive (false).
schedule.period.intervalIntegerThe interval at which the detector runs.
schedule.period.unitStringThe interval’s unit of time.
inputs.input.descriptionStringDescription of the detector.
inputs.input.indicesArrayThe log data source used for the detector. Only one source is allowed at this time.
inputs.input.rules.idArrayA list of security rules for the detector definition.
triggers.sev_levelsArraySigma rule severity levels: informational; low; medium; high; criticial. See Level in the Sigma Rule Creation Guide.
triggers.tagsArrayTags 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.actionsObjectActions send notifications when trigger conditions are met. See trigger actions for Create Detector API.

Example request

  1. PUT /_plugins/_security_analytics/detectors/J1RX1IMByX0LvTiGTddR
  2. {
  3.   "type": "detector",
  4.   "detector_type": "windows",
  5.   "name": "windows_detector",
  6.   "enabled": true,
  7.   "createdBy": "chip",
  8.   "schedule": {
  9.     "period": {
  10.       "interval": 1,
  11.       "unit": "MINUTES"
  12.     }
  13.   },
  14.   "inputs": [
  15.     {
  16.       "input": {
  17.         "description": "windows detector for security analytics",
  18.         "indices": [
  19.           "windows"
  20.         ],
  21.         "custom_rules": [],
  22.         "pre_packaged_rules": [
  23.           {
  24.             "id": "73a883d0-0348-4be4-a8d8-51031c2564f8"
  25.           },
  26.           {
  27.             "id": "1a4bd6e3-4c6e-405d-a9a3-53a116e341d4"
  28.           }
  29.         ]
  30.       }
  31.     }
  32.   ],
  33.   "triggers": [
  34.     {
  35.       "sev_levels": [],
  36.       "tags": [],
  37.       "actions": [],
  38.       "types": [
  39.         "windows"
  40.       ],
  41.       "name": "test-trigger",
  42.       "id": "fyAy1IMBK2A1DZyOuW_b"
  43.     }
  44.   ]
  45. }

copy

Example response

  1. {
  2.     "_id": "J1RX1IMByX0LvTiGTddR",
  3.     "_version": 1,
  4.     "detector": {
  5.         "name": "windows_detector",
  6.         "detector_type": "windows",
  7.         "enabled": true,
  8.         "schedule": {
  9.             "period": {
  10.                 "interval": 1,
  11.                 "unit": "MINUTES"
  12.             }
  13.         },
  14.         "inputs": [
  15.             {
  16.                 "detector_input": {
  17.                     "description": "windows detector for security analytics",
  18.                     "indices": [
  19.                         "windows"
  20.                     ],
  21.                     "rules": [
  22.                         {
  23.                             "id": "LFRY1IMByX0LvTiGZtfh"
  24.                         }
  25.                     ]
  26.                 }
  27.             }
  28.         ],
  29.         "triggers": [],
  30.         "last_update_time": "2022-10-14T02:36:32.909581688Z",
  31.         "enabled_time": "2022-10-14T02:33:34.197Z"
  32.     }
  33. }

Response body fields

FieldTypeDescription
_versionStringVersion number for the update.
detector.last_update_timeStringDate and time of the last update.
detector.enabled_timeStringDate 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

  1. DELETE /_plugins/_security_analytics/detectors/IJAXz4QBrmVplM4JYxx_

Example request

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

copy

Example response

  1. {
  2.   "_id" : "IJAXz4QBrmVplM4JYxx_",
  3.   "_version" : 1
  4. }

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

  1. GET /_plugins/_security_analytics/detectors/x-dwFIYBT6_n8WeuQjo4

Example request

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

copy

Example response

  1. {
  2.   "_id" : "x-dwFIYBT6_n8WeuQjo4",
  3.   "_version" : 1,
  4.   "detector" : {
  5.     "name" : "DetectorTest1",
  6.     "detector_type" : "windows",
  7.     "enabled" : true,
  8.     "schedule" : {
  9.       "period" : {
  10.         "interval" : 1,
  11.         "unit" : "MINUTES"
  12.       }
  13.     },
  14.     "inputs" : [
  15.       {
  16.         "detector_input" : {
  17.           "description" : "Test and delete",
  18.           "indices" : [
  19.             "windows1"
  20.           ],
  21.           "custom_rules" : [ ],
  22.           "pre_packaged_rules" : [
  23.             {
  24.               "id" : "847def9e-924d-4e90-b7c4-5f581395a2b4"
  25.             }
  26.           ]
  27.         }
  28.       }
  29.     ],
  30.     "last_update_time" : "2023-02-02T23:22:26.454Z",
  31.     "enabled_time" : "2023-02-02T23:22:26.454Z"
  32.   }
  33. }

Search Detector API

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

Request body fields

FieldTypeDescription
_idStringVersion number for the update.
detector.nameStringName of the detector.
detector_typeStringThe log type for the detector. Options are linux, network ,windows, ad_ldap, apache_access, cloudtrail, dns, and s3.

Example request

Detector ID

  1. POST /_plugins/_security_analytics/detectors/_search
  2. {
  3.     "query": {
  4.         "match": {
  5.             "_id": "MFRg1IMByX0LvTiGHtcN"
  6.         }
  7.     }
  8. }

copy

Detector name

  1. POST /_plugins/_security_analytics/detectors/_search
  2. {
  3.   "size": 30,  
  4.   "query": {
  5.     "nested": {
  6.       "path": "detector",
  7.       "query": {
  8.         "bool": {
  9.           "must": [
  10.             { "match": {"detector.name": "DetectorTest1"} }
  11.           ]
  12.         }
  13.       }
  14.     }
  15.   }
  16. }

copy

Example response

  1. {
  2.   "took" : 0,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 3.671739,
  16.     "hits" : [
  17.       {
  18.         "_index" : ".opensearch-sap-detectors-config",
  19.         "_id" : "x-dwFIYBT6_n8WeuQjo4",
  20.         "_version" : 1,
  21.         "_seq_no" : 76,
  22.         "_primary_term" : 17,
  23.         "_score" : 3.671739,
  24.         "_source" : {
  25.           "type" : "detector",
  26.           "name" : "DetectorTest1",
  27.           "detector_type" : "windows",
  28.           "enabled" : true,
  29.           "enabled_time" : 1675380146454,
  30.           "schedule" : {
  31.             "period" : {
  32.               "interval" : 1,
  33.               "unit" : "MINUTES"
  34.             }
  35.           },
  36.           "inputs" : [
  37.             {
  38.               "detector_input" : {
  39.                 "description" : "Test and delete",
  40.                 "indices" : [
  41.                   "windows1"
  42.                 ],
  43.                 "custom_rules" : [ ],
  44.                 "pre_packaged_rules" : [
  45.                   {
  46.                     "id" : "847def9e-924d-4e90-b7c4-5f581395a2b4"
  47.                   }
  48.                 ]
  49.               }
  50.             }
  51.           ],
  52.           "triggers" : [
  53.             {
  54.               "id" : "w-dwFIYBT6_n8WeuQToW",
  55.               "name" : "trigger 1",
  56.               "severity" : "1",
  57.               "types" : [
  58.                 "windows"
  59.               ],
  60.               "ids" : [
  61.                 "847def9e-924d-4e90-b7c4-5f581395a2b4"
  62.               ],
  63.               "sev_levels" : [
  64.                 "critical"
  65.               ],
  66.               "tags" : [
  67.                 "attack.t1003.002"
  68.               ],
  69.               "actions" : [
  70.                 {
  71.                   "id" : "",
  72.                   "name" : "Triggered alert condition:  - Severity: 1 (Highest) - Threat detector: DetectorTest1",
  73.                   "destination_id" : "",
  74.                   "message_template" : {
  75.                     "source" : """Triggered alert condition: 
  76. Severity: 1 (Highest)
  77. Threat detector: DetectorTest1
  78. Description: Test and delete
  79. Detector data sources:
  80.   windows1""",
  81.                     "lang" : "mustache"
  82.                   },
  83.                   "throttle_enabled" : false,
  84.                   "subject_template" : {
  85.                     "source" : "Triggered alert condition:  - Severity: 1 (Highest) - Threat detector: DetectorTest1",
  86.                     "lang" : "mustache"
  87.                   },
  88.                   "throttle" : {
  89.                     "value" : 10,
  90.                     "unit" : "MINUTES"
  91.                   }
  92.                 }
  93.               ]
  94.             }
  95.           ],
  96.           "last_update_time" : 1675380146454,
  97.           "monitor_id" : [
  98.             "xOdwFIYBT6_n8WeuQToa"
  99.           ],
  100.           "bucket_monitor_id_rule_id" : {
  101.             "-1" : "xOdwFIYBT6_n8WeuQToa"
  102.           },
  103.           "rule_topic_index" : ".opensearch-sap-windows-detectors-queries",
  104.           "alert_index" : ".opensearch-sap-windows-alerts",
  105.           "alert_history_index" : ".opensearch-sap-windows-alerts-history",
  106.           "alert_history_index_pattern" : "<.opensearch-sap-windows-alerts-history-{now/d}-1>",
  107.           "findings_index" : ".opensearch-sap-windows-findings",
  108.           "findings_index_pattern" : "<.opensearch-sap-windows-findings-{now/d}-1>"
  109.         }
  110.       }
  111.     ]
  112.   }
  113. }