You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
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.
POST _plugins/_security_analytics/threat_intel/monitors
PUT _plugins/_security_analytics/threat_intel/monitors/<monitor_id>
Request body fields
You can specify the following fields in the request body.
| Field | Type | Description |
|---|---|---|
name | String | The name of the monitor. Required. |
schedule | Object | The schedule that determines how often the monitor runs. Required. |
schedule.period | Object | Information about the frequency of the schedule. Required. |
schedule.period.interval | Integer | The interval at which the monitor runs. Required. |
schedule.period.unit | String | The unit of time for the interval. |
enabled | Object | Information about the user who created the monitor. Required. |
user.backend_roles | Array | The backend roles associated with the user. Optional. |
user.roles | Array | The roles associated with the user. Optional. |
user.custom_attribute_names | Array | Custom attribute names associated with the user. Optional. |
user.user_requested_tenant | String | The tenant requested by the user. Optional. |
indices | Array | The log data sources used for the monitor. Required. |
per_ioc_type_scan_input_list | Array | A list of inputs to scan based on the indicator of compromise (IOC) types. Required. |
per_ioc_type_scan_input_list.ioc_type | String | The type of IOC (for example, hashes). Required. |
per_ioc_type_scan_input_list.index_to_fields_map | Object | The index field mappings that contain values for the given IOC type. Required. |
per_ioc_type_scan_input_list.index_to_fields_map.<index> | Array | A list of fields contained in the specified index. Required. |
triggers | Array | The trigger settings for alerts. Required. |
triggers.data_sources | Array | A list of data sources associated with the trigger. Required. |
triggers.name | String | The name of the trigger. Required. |
triggers.severity | String | The 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
{
"name": "Threat intel monitor",
"schedule": {
"period": {
"interval": 1,
"unit": "MINUTES"
}
},
"enabled": false,
"user": {
"name": "",
"backend_roles": [],
"roles": [],
"custom_attribute_names": [],
"user_requested_tenant": null
},
"indices": [
"windows"
],
"per_ioc_type_scan_input_list": [
{
"ioc_type": "hashes",
"index_to_fields_map": {
"windows": [
"file_hash"
]
}
}
],
"triggers": [
{
"data_sources": [
"windows",
"random"
],
"name": "regwarg",
"severity": "high"
}
]
}
Update a monitor
{
"name": "Threat intel monitor",
"schedule": {
"period": {
"interval": 1,
"unit": "MINUTES"
}
},
"enabled": false,
"user": {
"name": "",
"backend_roles": [],
"roles": [],
"custom_attribute_names": [],
"user_requested_tenant": null
},
"indices": [
"windows"
],
"per_ioc_type_scan_input_list": [
{
"ioc_type": "hashes",
"index_to_fields_map": {
"windows": [
"file_hash"
]
}
}
],
"triggers": [
{
"data_sources": [
"windows",
"random"
],
"name": "regwarg",
"severity": "high"
}
]
}
Example response
{
"id": "B8p88ZAB1vBjq44wkjEy",
"name": 1,
"seq_no": 0,
"primary_term": 1,
"monitor": {
"id": "B8p88ZAB1vBjq44wkjEy",
"name": "Threat intel monitor",
"per_ioc_type_scan_input_list": [
{
"ioc_type": "hashes",
"index_to_fields_map": {
"windows": [
"file_hash"
]
}
}
],
"schedule": {
"period": {
"interval": 1,
"unit": "MINUTES"
}
},
"enabled": false,
"user": {
"name": "",
"backend_roles": [],
"roles": [],
"custom_attribute_names": [],
"user_requested_tenant": null
},
"indices": [
"windows"
],
"triggers": [
{
"data_sources": [
"windows",
"random"
],
"ioc_types": [],
"actions": [],
"id": "afdd80cc-a669-4487-98a0-d84bea8e1e39",
"name": "regwarg",
"severity": "high"
}
]
}
}
Delete a monitor
Deletes an existing threat intelligence monitor.
Path and HTTP methods
DELETE /_plugins/_security_analytics/threat_intel/monitors/<monitor_id>
Example request
DELETE /_plugins/_security_analytics/threat_intel/monitors/B8p88ZAB1vBjq44wkjEy
Example response
{
"_id" : "B8p88ZAB1vBjq44wkjEy",
"_version" : 1
}
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:
POST /_plugins/_security_analytics/detectors/_search
{
"query": {
"match": {
"_id": "HMqq_5AB1vBjq44wpTIN"
}
}
}
Example response
{
"took": 11,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 2.0,
"hits": [
{
"_index": ".opendistro-alerting-config",
"_id": "HMqq_5AB1vBjq44wpTIN",
"_version": 1,
"_seq_no": 8,
"_primary_term": 1,
"_score": 2.0,
"_source": {
"id": "HMqq_5AB1vBjq44wpTIN",
"name": "Threat intel monitor",
"per_ioc_type_scan_input_list": [
{
"ioc_type": "hashes",
"index_to_fields_map": {
"windows": [
"file_hash"
]
}
}
],
"schedule": {
"period": {
"interval": 1,
"unit": "MINUTES"
}
},
"enabled": false,
"user": {
"name": "",
"backend_roles": [],
"roles": [],
"custom_attribute_names": [],
"user_requested_tenant": null
},
"indices": [
"windows"
],
"triggers": [
{
"data_sources": [
"windows",
"random"
],
"ioc_types": [],
"actions": [],
"id": "63426758-c82d-4c87-a52c-f86ee6a8a06d",
"name": "regwarg",
"severity": "high"
}
]
}
}
]
}
}