Monitor API

You can use the threat intelligence Monitor API to create, search, and update monitors for your threat intelligence feeds.

Create or update a threat intelligence monitor

Creates or updates a threat intelligence monitor.

Path and HTTP methods

The POST method creates a new monitor. The PUT method updates a monitor.

  1. POST _plugins/_security_analytics/threat_intel/monitors
  2. PUT _plugins/_security_analytics/threat_intel/monitors/<monitor_id>

Request fields

You can specify the following fields in the request body.

FieldTypeDescription
nameStringThe name of the monitor. Required.
scheduleObjectThe schedule that determines how often the monitor runs. Required.
schedule.periodObjectInformation about the frequency of the schedule. Required.
schedule.period.intervalIntegerThe interval at which the monitor runs. Required.
schedule.period.unitStringThe unit of time for the interval.
enabledObjectInformation about the user who created the monitor. Required.
user.backend_rolesArrayThe backend roles associated with the user. Optional.
user.rolesArrayThe roles associated with the user. Optional.
user.custom_attribute_namesArrayCustom attribute names associated with the user. Optional.
user.user_requested_tenantStringThe tenant requested by the user. Optional.
indicesArrayThe log data sources used for the monitor. Required.
per_ioc_type_scan_input_listArrayA list of inputs to scan based on the indicator of compromise (IOC) types. Required.
per_ioc_type_scan_input_list.ioc_typeStringThe type of IOC (for example, hashes). Required.
per_ioc_type_scan_input_list.index_to_fields_mapObjectThe index field mappings that contain values for the given IOC type. Required.
per_ioc_type_scan_input_list.index_to_fields_map.<index>ArrayA list of fields contained in the specified index. Required.
triggersArrayThe trigger settings for alerts. Required.
triggers.data_sourcesArrayA list of data sources associated with the trigger. Required.
triggers.nameStringThe name of the trigger. Required.
triggers.severityStringThe severity level of the trigger (for example, high, medium, or low). Required.

Example requests

The following section provides example requests for the Monitor API.

Create a monitor

  1. {
  2.     "name": "Threat intel monitor",
  3.     "schedule": {
  4.         "period": {
  5.             "interval": 1,
  6.             "unit": "MINUTES"
  7.         }
  8.     },
  9.     "enabled": false,
  10.     "user": {
  11.         "name": "",
  12.         "backend_roles": [],
  13.         "roles": [],
  14.         "custom_attribute_names": [],
  15.         "user_requested_tenant": null
  16.     },
  17.     "indices": [
  18.         "windows"
  19.     ],
  20.     "per_ioc_type_scan_input_list": [
  21.         {
  22.             "ioc_type": "hashes",
  23.             "index_to_fields_map": {
  24.                 "windows": [
  25.                     "file_hash"
  26.                 ]
  27.             }
  28.         }
  29.     ],
  30.   "triggers": [
  31.         {
  32.             "data_sources": [
  33.                 "windows",
  34.                 "random"
  35.             ],
  36.             "name": "regwarg",
  37.             "severity": "high"
  38.         }
  39.     ]
  40. }

Update a monitor

  1. {
  2.     "name": "Threat intel monitor",
  3.     "schedule": {
  4.         "period": {
  5.             "interval": 1,
  6.             "unit": "MINUTES"
  7.         }
  8.     },
  9.     "enabled": false,
  10.     "user": {
  11.         "name": "",
  12.         "backend_roles": [],
  13.         "roles": [],
  14.         "custom_attribute_names": [],
  15.         "user_requested_tenant": null
  16.     },
  17.     "indices": [
  18.         "windows"
  19.     ],
  20.     "per_ioc_type_scan_input_list": [
  21.         {
  22.             "ioc_type": "hashes",
  23.             "index_to_fields_map": {
  24.                 "windows": [
  25.                     "file_hash"
  26.                 ]
  27.             }
  28.         }
  29.     ],
  30.   "triggers": [
  31.         {
  32.             "data_sources": [
  33.                 "windows",
  34.                 "random"
  35.             ],
  36.             "name": "regwarg",
  37.             "severity": "high"
  38.         }
  39.     ]
  40. }

Example response

  1. {
  2.     "id": "B8p88ZAB1vBjq44wkjEy",
  3.     "name": 1,
  4.     "seq_no": 0,
  5.     "primary_term": 1,
  6.     "monitor": {
  7.         "id": "B8p88ZAB1vBjq44wkjEy",
  8.         "name": "Threat intel monitor",
  9.         "per_ioc_type_scan_input_list": [
  10.             {
  11.                 "ioc_type": "hashes",
  12.                 "index_to_fields_map": {
  13.                     "windows": [
  14.                         "file_hash"
  15.                     ]
  16.                 }
  17.             }
  18.         ],
  19.         "schedule": {
  20.             "period": {
  21.                 "interval": 1,
  22.                 "unit": "MINUTES"
  23.             }
  24.         },
  25.         "enabled": false,
  26.         "user": {
  27.             "name": "",
  28.             "backend_roles": [],
  29.             "roles": [],
  30.             "custom_attribute_names": [],
  31.             "user_requested_tenant": null
  32.         },
  33.         "indices": [
  34.             "windows"
  35.         ],
  36.         "triggers": [
  37.             {
  38.                 "data_sources": [
  39.                     "windows",
  40.                     "random"
  41.                 ],
  42.                 "ioc_types": [],
  43.                 "actions": [],
  44.                 "id": "afdd80cc-a669-4487-98a0-d84bea8e1e39",
  45.                 "name": "regwarg",
  46.                 "severity": "high"
  47.             }
  48.         ]
  49.     }
  50. }

Delete a monitor

Deletes an existing threat intelligence monitor.

Path and HTTP methods

  1. DELETE /_plugins/_security_analytics/threat_intel/monitors/<monitor_id>

Example request

  1. DELETE /_plugins/_security_analytics/threat_intel/monitors/B8p88ZAB1vBjq44wkjEy

copy

Example response

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

Search for a monitor

Searches for an existing monitor using a query. The request body expects a search query. For query options, see Query DSL.

Example request

The following example request using a match query with the monitor’s ID to search for the monitor:

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

copy

Example response

  1. {
  2.   "took": 11,
  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": 2.0,
  16.     "hits": [
  17.       {
  18.         "_index": ".opendistro-alerting-config",
  19.         "_id": "HMqq_5AB1vBjq44wpTIN",
  20.         "_version": 1,
  21.         "_seq_no": 8,
  22.         "_primary_term": 1,
  23.         "_score": 2.0,
  24.         "_source": {
  25.           "id": "HMqq_5AB1vBjq44wpTIN",
  26.           "name": "Threat intel monitor",
  27.           "per_ioc_type_scan_input_list": [
  28.             {
  29.               "ioc_type": "hashes",
  30.               "index_to_fields_map": {
  31.                 "windows": [
  32.                   "file_hash"
  33.                 ]
  34.               }
  35.             }
  36.           ],
  37.           "schedule": {
  38.             "period": {
  39.               "interval": 1,
  40.               "unit": "MINUTES"
  41.             }
  42.           },
  43.           "enabled": false,
  44.           "user": {
  45.             "name": "",
  46.             "backend_roles": [],
  47.             "roles": [],
  48.             "custom_attribute_names": [],
  49.             "user_requested_tenant": null
  50.           },
  51.           "indices": [
  52.             "windows"
  53.           ],
  54.           "triggers": [
  55.             {
  56.               "data_sources": [
  57.                 "windows",
  58.                 "random"
  59.               ],
  60.               "ioc_types": [],
  61.               "actions": [],
  62.               "id": "63426758-c82d-4c87-a52c-f86ee6a8a06d",
  63.               "name": "regwarg",
  64.               "severity": "high"
  65.             }
  66.           ]
  67.         }
  68.       }
  69.     ]
  70.   }
  71. }