Get Alerts

Synopsis

URI
/public_api/v1/alerts/get_alerts_multi_events/
HTTP Method
POST
Required License
Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per TB

Description

Get a list of alerts with multiple events.
  • Response is concatenated using AND condition (OR is not supported).
  • Maximum result set size is 100.
  • Offset is the zero-based number of alerts from the start of the result set.

Fields

The body of this request contains a JSON object with the following fields:
You can send a request to retrieve either
all
or
filtered
results.
Field
Description
request_data
(
Required
) A dictionary containing the API request fields.
An empty dictionary returns all results.
filters
Provides an array of filtered fields. Each JSON object can contain the following keywords:
  • field
    Identifies the alert field the filter is matching. Filters are based on the following keywords:
    • alert_id_list
      —List of integers of the Alert ID
    • alert_source
      —List of strings of the Alert source
    • severity
      —List of strings of the Alert severity
    • creation_time
      —Integer of the Creation time
  • operator
    String that identifies the comparison operator you want to use for this filter. Values keywords:
    in
    • - Permitted for
      alert_id
      ,
      alert_source
      , and
      severity
      .
    gte
    /
    lte
    • Permitted only for
      creation_time
      .
  • value
    Value that this filter must match. The contents of this field will differ depending on the alert field that you specified for this filter:
    • creation_time
      —Integer representing the number of seconds or milliseconds after the Unix epoch, UTC timezone. The value is returned in the response under the
      detection_timestamp
      field, and represented in console under the
      TIMESTAMP
      field.
    • alert_id_list
      —List of integers. Each item in the list must be an alert ID.
    • severity
      Valid values:
      low
      ,
      medium
      ,
      high
      ,
      unknown
search_from
An integer representing the starting offset within the query result set from which you want alerts returned.
Alerts are returned as a zero-based list. Any alert indexed less than this value is not returned in the final result set and defaults to zero.
search_to
An integer representing the end offset within the result set after which you do not want alerts returned.
Alerts in the alerts list that are indexed higher than this value are not returned in the final results set. Defaults to 100, which returns all alerts to the end of the list.
sort
Identifies the sort order for the result set. By default the sort is defined as
creation-_time
,
desc
.
  • field
    —Can either be
    severity
    or
    creation_time
    .
  • keyword
    —Can either be
    asc
    (ascending order) or
    desc
    (descending order).
Request Example
Request all results:
curl -X POST https://api-{fqdn}/public_api/v1/alerts/get_alerts/ \ -H "x-xdr-auth-id:{API_KEY_ID}" \ -H "Authorization:{API_KEY}" \ -H "Content-Type:application/json" \ -d '{ "request_data":{} }'
Code copied to clipboard
Unable to copy due to lack of browser support.
Request filtered results:
curl -X POST https://api-{fqdn}/public_api/v1/alerts/get_alerts_multi_events/ \ -H "x-xdr-auth-id:{API_KEY_ID}" \ -H "Authorization:{API_KEY}" \ -H "Content-Type:application/json" \ -d '{ "request_data":{ "filters":[ { "field":"severity", "operator":"in", "value":[ "medium", "high" ] } ], "search_from":0, "search_to":5, "sort":{ "field":"severity", "keyword":"asc" } } }’
Code copied to clipboard
Unable to copy due to lack of browser support.

Success Response

Upon success, the HTTP response code is 200. In addition, this API returns a JSON object containing the query status, as well as an array of JSON objects, each of which represents a single alert.
Field
Description
reply
JSON object containing the query result.
total_count
Number of total results of this filter without paging. If filter returned 10,000 results or more than 9,999 will be the value and you can use paging to view the entire set of data.
result_count
Number of alerts actually returned as result (integer).
alerts
A list of alerts (list).
Success Response Example
{ "reply":{ "total_count":45, "result_count":1, "alerts":[ { "external_id":"<external ID>", "severity":"high", "matching_status":"FAILED", "end_match_attempt_ts":1603552062824, "local_insert_ts":1603279967500, "bioc_indicator":null, "matching_service_rule_id":null, "attempt_counter":55, "bioc_category_enum_key":null, "is_whitelisted":false, "starred":false, "deduplicate_tokens":null, "filter_rule_id":null, "mitre_technique_id_and_name":[ "" ], "mitre_tactic_id_and_name":[ "" ], "agent_version":"<agent version>", "agent_device_domain":null, "agent_fqdn":"test", "agent_os_type":"Windows", "agent_os_sub_type":"<os subtype>", "agent_data_collection_status":true, "mac":null, "mac_address": [ "<mac address>" ], "agent_is_vdi": null, "contains_featured_host": true, "contains_featured_user": true, "contains_featured_ip": true, "events":[ { "agent_install_type":"NA", "agent_host_boot_time":null, "event_sub_type":null, "module_id":"Privilege Escalation Protection", "association_strength":null, "dst_association_strength":null, "story_id":null, "event_id":null, "event_type":"Process Execution", "event_timestamp":1603279888980, "actor_process_instance_id":"<instance ID>", "actor_process_image_path":"c:\\<file path>\\virus.exe", "actor_process_image_name":"virus.exe", "actor_process_command_line":"c:\\<file path>\\virus.exe", "actor_process_signature_status":"N/A", "actor_process_signature_vendor":null, "actor_process_image_sha256":"<SHA256 value>", "actor_process_image_md5":null, "actor_process_causality_id":null, "actor_causality_id":null, "actor_process_os_pid":"<PID>", "actor_thread_thread_id":null, "causality_actor_process_image_name":null, "causality_actor_process_command_line":null, "causality_actor_process_image_path":null, "causality_actor_process_signature_vendor":null, "causality_actor_process_signature_status":"N/A", "causality_actor_causality_id":null, "causality_actor_process_execution_time":null, "causality_actor_process_image_md5":null, "causality_actor_process_image_sha256":null, "action_file_path":null, "action_file_name":null, "action_file_md5":null, "action_file_sha256":null, "action_file_macro_sha256":null, "action_registry_data":null, "action_registry_key_name":null, "action_registry_value_name":null, "action_registry_full_key":null, "action_local_ip":null, "action_local_port":null, "action_remote_ip":null, "action_remote_port":null, "action_external_hostname":null, "action_country":"UNKNOWN", "action_process_instance_id":null, "action_process_causality_id":null, "action_process_image_name":null, "action_process_image_sha256":null, "action_process_image_command_line":null, "action_process_signature_status":"N/A", "action_process_signature_vendor":null, "os_actor_effective_username":null, "os_actor_process_instance_id":null, "os_actor_process_image_path":null, "os_actor_process_image_name":null, "os_actor_process_command_line":null, "os_actor_process_signature_status":"N/A", "os_actor_process_signature_vendor":null, "os_actor_process_image_sha256":null, "os_actor_process_causality_id":null, "os_actor_causality_id":null, "os_actor_process_os_pid":null, "os_actor_thread_thread_id":null, "fw_app_id":null, "fw_interface_from":null, "fw_interface_to":null, "fw_rule":null, "fw_rule_id":null, "fw_device_name":null, "fw_serial_number":null, "fw_url_domain":null, "fw_email_subject":null, "fw_email_sender":null, "fw_email_recipient":null, "fw_app_subcategory":null, "fw_app_category":null, "fw_app_technology":null, "fw_vsys":null, "fw_xff":null, "fw_misc":null, "fw_is_phishing":"N/A", "dst_agent_id":null, "dst_causality_actor_process_execution_time":null, "dns_query_name":null, "dst_action_external_hostname":null, "dst_action_country":null, "dst_action_external_port":null, "user_name":null } ], "alert_id":"<alert ID>", "detection_timestamp":1603279888980, "name":"Kernel Privilege Escalation", "category":"Exploit", "endpoint_id":"<endpoint ID>", "description":"Local privilege escalation prevented", "host_ip":[ "<IP address>" ], "host_name":"Test", "source":"XDR Agent", "action":"BLOCKED", "action_pretty":"Prevented (Blocked)" } ] } }
Code copied to clipboard
Unable to copy due to lack of browser support.

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:
Field
Description
400
Bad Request. Got an invalid JSON.
401
Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.
402
Unauthorized access. User does not have the required license type to run this API.
403
Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{"reply": {"err_code": STATUS_CODE, "err_msg": GENERAL_MESSAGE, "err_extra": EXTRA_DATA}}
Code copied to clipboard
Unable to copy due to lack of browser support.

Recommended For You