Alerts and findings APIs

The following APIs can be used for tasks related to alerts and findings.

Get alerts

Provides an option for retrieving alerts related to a specific detector type or detector ID.

Parameters

You can specify the following parameters when requesting an alert.

ParameterDescription
detector_idThe ID of the detector used to fetch alerts. Optional when the detectorType is specified. Otherwise required.
detectorTypeThe type of detector used to fetch alerts. Optional when the detector_Id is specified. Otherwise required.
severityLevelUsed to filter by alert severity level. Optional.
alertStateUsed to filter by alert state. Possible values are ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, or DELETED. Optional.
sortStringThis field specifies which string Security Analytics uses to sort the alerts. Optional.
sortOrderThe order used to sort the list of findings. Possible values are asc or desc. Optional.
missingA list of fields for which there are no found alias mappings. Optional.
sizeAn optional limit for the maximum number of results returned in the response. Optional.
startIndexThe pagination indicator. Optional.
searchStringThe alert attribute you want returned in the search. Optional.

Example request

  1. GET /_plugins/_security_analytics/alerts?detectorType=windows

Example response

  1. {
  2.     "alerts": [{
  3.         "detector_id": "detector_12345",
  4.         "id": "alert_id_1",
  5.         "version": -3,
  6.         "schema_version": 0,
  7.         "trigger_id": "trigger_id_1",
  8.         "trigger_name": "my_trigger",
  9.         "finding_ids": ["finding_id_1"],
  10.         "related_doc_ids": ["docId1"],
  11.         "state": "ACTIVE",
  12.         "error_message": null,
  13.         "alert_history": [],
  14.         "severity": null,
  15.         "action_execution_results": [{
  16.             "action_id": "action_id_1",
  17.             "last_execution_time": 1665693544996,
  18.             "throttled_count": 0
  19.         }],
  20.         "start_time": "2022-10-13T20:39:04.995023Z",
  21.         "last_notification_time": "2022-10-13T20:39:04.995028Z",
  22.         "end_time": "2022-10-13T20:39:04.995027Z",
  23.         "acknowledged_time": "2022-10-13T20:39:04.995028Z"
  24.     }],
  25.     "total_alerts": 1,
  26.     "detectorType": "windows"
  27. }

Response fields

Alerts persist until you resolve the root cause and have the following states:

StateDescription
ACTIVEThe alert is ongoing and unacknowledged. Alerts remain in this state until you acknowledge them, delete the trigger associated with the alert, or delete the monitor entirely.
ACKNOWLEDGEDSomeone has acknowledged the alert but not fixed the root cause.
COMPLETEDThe alert is no longer ongoing. Alerts enter this state after the corresponding trigger evaluates to false.
ERRORAn error occurred while executing the trigger. This error is usually the result of a bad trigger or destination.
DELETEDSomeone deleted the detector or trigger associated with this alert while the alert was ongoing.

Acknowledge alerts

Sends an acknowledgement when an alert is triggered.

Example request

  1. POST /_plugins/_security_analytics/detectors/<detector_id>/_acknowledge/alerts
  3. {"alerts":["4dc7f5a9-2c82-4786-81ca-433a209d5205"]}

Example response

  1. {
  2.   "acknowledged": [
  3.     {
  4.       "detector_id": "8YT5fYQBZ8IUM4axics6",
  5.       "id": "4dc7f5a9-2c82-4786-81ca-433a209d5205",
  6.       "version": 1,
  7.       "schema_version": 4,
  8.       "trigger_id": "1TP5fYQBMkkIGY6Pg-q8",
  9.       "trigger_name": "test-trigger",
  10.       "finding_ids": [
  11.         "2e167f4b-8063-40ef-80f8-2afd9bf095b8"
  12.       ],
  13.       "related_doc_ids": [
  14.         "1|windows"
  15.       ],
  16.       "state": "ACTIVE",
  17.       "error_message": null,
  18.       "alert_history": [],
  19.       "severity": "1",
  20.       "action_execution_results": [
  21.         {
  22.           "action_id": "BopdoIJKXd",
  23.           "last_execution_time": 1668560817925,
  24.           "throttled_count": 0
  25.         }
  26.       ],
  27.       "start_time": "2022-11-16T01:06:57.748Z",
  28.       "last_notification_time": "2022-11-16T01:06:57.748Z",
  29.       "end_time": null,
  30.       "acknowledged_time": null
  31.     }
  32.   ],
  33.   "failed": [],
  34.   "missing": []
  35. }

Get findings

The Get findings API returns findings based on the detector attributes.

Parameters

You can specify the following parameters when getting findings.

ParameterDescription
detector_idThe ID of the detector used to fetch alerts. Optional.
detectorTypeThe type of detector used to fetch alerts. Optional.
sortOrderThe order used to sort the list of findings. Possible values are asc or desc. Optional.
sizeAn optional limit for the maximum number of results returned in the response. Optional.
startIndexThe pagination indicator. Optional.
detectionTypeThe detection rule type that dictates the retrieval type for the findings. When the detection type is threat, it fetches threat intelligence feeds. When the detection type is rule, findings are fetched based on the detector’s rule. Optional.
severityThe severity of the detector rule used to fetch alerts. Severity can be critical, high, medium, or low. Optional.

Example request

  1. GET /_plugins/_security_analytics/findings/_search
  2. {
  3.   "total_findings": 2,
  4.   "findings": [
  5.     {
  6.       "detectorId": "b9ZN040Bjlggkcgx1d1W",
  7.       "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
  8.       "related_doc_ids": [
  9.         "1"
  10.       ],
  11.       "index": "smallidx",
  12.       "queries": [
  13.         {
  14.           "id": "QdZN040Bjlggkcgxdd3X",
  15.           "name": "QdZN040Bjlggkcgxdd3X",
  16.           "fields": [],
  17.           "query": "field1: *value1*",
  18.           "tags": [
  19.             "high",
  20.             "ad_ldap"
  21.           ]
  22.         }
  23.       ],
  24.       "timestamp": 1708647166500,
  25.       "document_list": [
  26.         {
  27.           "index": "smallidx",
  28.           "id": "1",
  29.           "found": true,
  30.           "document": "{\n  \"field1\": \"value1\"\n}\n"
  31.         }
  32.       ]
  33.     },
  34.     {
  35.       "detectorId": "O9ZM040Bjlggkcgx6N1S",
  36.       "id": "a5022930-4503-4ca8-bf0a-320a2b1fb433",
  37.       "related_doc_ids": [
  38.         "1"
  39.       ],
  40.       "index": "smallidx",
  41.       "queries": [
  42.         {
  43.           "id": "KtZM040Bjlggkcgxkd04",
  44.           "name": "KtZM040Bjlggkcgxkd04",
  45.           "fields": [],
  46.           "query": "field1: *value1*",
  47.           "tags": [
  48.             "critical",
  49.             "ad_ldap"
  50.           ]
  51.         }
  52.       ],
  53.       "timestamp": 1708647166500,
  54.       "document_list": [
  55.         {
  56.           "index": "smallidx",
  57.           "id": "1",
  58.           "found": true,
  59.           "document": "{\n  \"field1\": \"value1\"\n}\n"
  60.         }
  61.       ]
  62.     }
  63.   ]
  64. }
  1. GET /_plugins/_security_analytics/findings/_search?severity=high
  2. {
  3.     "total_findings": 1,
  4.     "findings": [
  5.         {
  6.             "detectorId": "b9ZN040Bjlggkcgx1d1W",
  7.             "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
  8.             "related_doc_ids": [
  9.                 "1"
  10.             ],
  11.             "index": "smallidx",
  12.             "queries": [
  13.                 {
  14.                     "id": "QdZN040Bjlggkcgxdd3X",
  15.                     "name": "QdZN040Bjlggkcgxdd3X",
  16.                     "fields": [],
  17.                     "query": "field1: *value1*",
  18.                     "tags": [
  19.                         "high",
  20.                         "ad_ldap"
  21.                     ]
  22.                 }
  23.             ],
  24.             "timestamp": 1708647166500,
  25.             "document_list": [
  26.                 {
  27.                     "index": "smallidx",
  28.                     "id": "1",
  29.                     "found": true,
  30.                     "document": "{\n  \"field1\": \"value1\"\n}\n"
  31.                 }
  32.             ]
  33.         }
  34.     ]
  35. }
  1. GET /_plugins/_security_analytics/findings/_search?detectionType=rule
  2. {
  3.     "total_findings": 2,
  4.     "findings": [
  5.         {
  6.             "detectorId": "b9ZN040Bjlggkcgx1d1W",
  7.             "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
  8.             "related_doc_ids": [
  9.                 "1"
  10.             ],
  11.             "index": "smallidx",
  12.             "queries": [
  13.                 {
  14.                     "id": "QdZN040Bjlggkcgxdd3X",
  15.                     "name": "QdZN040Bjlggkcgxdd3X",
  16.                     "fields": [],
  17.                     "query": "field1: *value1*",
  18.                     "tags": [
  19.                         "high",
  20.                         "ad_ldap"
  21.                     ]
  22.                 }
  23.             ],
  24.             "timestamp": 1708647166500,
  25.             "document_list": [
  26.                 {
  27.                     "index": "smallidx",
  28.                     "id": "1",
  29.                     "found": true,
  30.                     "document": "{\n  \"field1\": \"value1\"\n}\n"
  31.                 }
  32.             ]
  33.         },
  34.         {
  35.             "detectorId": "O9ZM040Bjlggkcgx6N1S",
  36.             "id": "a5022930-4503-4ca8-bf0a-320a2b1fb433",
  37.             "related_doc_ids": [
  38.                 "1"
  39.             ],
  40.             "index": "smallidx",
  41.             "queries": [
  42.                 {
  43.                     "id": "KtZM040Bjlggkcgxkd04",
  44.                     "name": "KtZM040Bjlggkcgxkd04",
  45.                     "fields": [],
  46.                     "query": "field1: *value1*",
  47.                     "tags": [
  48.                         "critical",
  49.                         "ad_ldap"
  50.                     ]
  51.                 }
  52.             ],
  53.             "timestamp": 1708647166500,
  54.             "document_list": [
  55.                 {
  56.                     "index": "smallidx",
  57.                     "id": "1",
  58.                     "found": true,
  59.                     "document": "{\n  \"field1\": \"value1\"\n}\n"
  60.                 }
  61.             ]
  62.         }
  63.     ]
  64. }
  1. GET /_plugins/_security_analytics/findings/_search?detectionType=rule&severity=high
  2. {
  3.     "total_findings": 1,
  4.     "findings": [
  5.         {
  6.             "detectorId": "b9ZN040Bjlggkcgx1d1W",
  7.             "id": "35efb736-c5d9-499d-b9b5-31f0a7d61251",
  8.             "related_doc_ids": [
  9.                 "1"
  10.             ],
  11.             "index": "smallidx",
  12.             "queries": [
  13.                 {
  14.                     "id": "QdZN040Bjlggkcgxdd3X",
  15.                     "name": "QdZN040Bjlggkcgxdd3X",
  16.                     "fields": [],
  17.                     "query": "field1: *value1*",
  18.                     "tags": [
  19.                         "high",
  20.                         "ad_ldap"
  21.                     ]
  22.                 }
  23.             ],
  24.             "timestamp": 1708647166500,
  25.             "document_list": [
  26.                 {
  27.                     "index": "smallidx",
  28.                     "id": "1",
  29.                     "found": true,
  30.                     "document": "{\n  \"field1\": \"value1\"\n}\n"
  31.                 }
  32.             ]
  33.         }
  34.     ]
  35. }
  1. GET /_plugins/_security_analytics/findings/_search?*detectorType*=
  2. {
  3.     "total_findings":2,
  4.     "findings":[
  5.        {
  6.             "detectorId":"12345",
  7.             "id":"2b9663f4-ae77-4df8-b84f-688a0195723b",
  8.             "related_doc_ids":[
  9.                 "5"
  10.             ],
  11.             "index":"sbwhrzgdlg",
  12.             "queries":[
  13.                 {
  14.                     "id":"f1bff160-587b-4500-b60c-ab22c7abc652",
  15.                     "name":"3",
  16.                     "query":"test_field:\"us-west-2\"",
  17.                     "tags":[
  19.                     ]
  20.                 }
  21.             ],
  22.             "timestamp":1664401088804,
  23.             "document_list":[
  24.                 {
  25.                     "index":"sbwhrzgdlg",
  26.                     "id":"5",
  27.                     "found":true,
  28.                     "document":"{\n            \"message\" : \"This is an error from IAD region\",\n            \"test_strict_date_time\" : \"2022-09-28T21:38:02.888Z\",\n            \"test_field\" : \"us-west-2\"\n        }"
  29.                 }
  30.             ]
  31.         },
  32.         {
  33.             "detectorId":"12345",
  34.             "id":"f43a2701-0ef5-4931-8254-bdf510f73952",
  35.             "related_doc_ids":[
  36.                 "1"
  37.             ],
  38.             "index":"sbwhrzgdlg",
  39.             "queries":[
  40.                 {
  41.                     "id":"f1bff160-587b-4500-b60c-ab22c7abc652",
  42.                     "name":"3",
  43.                     "query":"test_field:\"us-west-2\"",
  44.                     "tags":[
  46.                     ]
  47.                 }
  48.             ],
  49.             "timestamp":1664401088746,
  50.             "document_list":[
  51.                 {
  52.                     "index":"sbwhrzgdlg",
  53.                     "id":"1",
  54.                     "found":true,
  55.                     "document":"{\n            \"message\" : \"This is an error from IAD region\",\n            \"test_strict_date_time\" : \"2022-09-28T21:38:02.888Z\",\n            \"test_field\" : \"us-west-2\"\n        }"
  56.                 }
  57.             ]
  58.         }
  59.     ]
  60. }