Get Correlation Rules

post /public_api/v1/correlations/get

Return a list of correlation rules. You can return all correlation rules or filter results. You can also return extended results with all details included.

The response is concatenated using AND condition (OR is not supported).
The maximum result set size is >100.
Offset is the zero-based number of incidents from the start of the result set.

You must have Instance Administrator permissions to run this endpoint.

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
      
      'https://api-yourfqdn/public_api/v1/correlations/get'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}"

headers = {
    'Authorization': "SOME_STRING_VALUE",
    'x-xdr-auth-id': "SOME_STRING_VALUE",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/correlations/get", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/v1/correlations/get")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "request_data": {
    "extended_view": true,
    "filters": [
      {
        "field": "name",
        "operator": "EQ",
        "value": "string"
      }
    ],
    "search_from": 0,
    "search_to": 0
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/v1/correlations/get");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/correlations/get")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "extended_view": true,
    "filters": [
      [
        "field": "name",
        "operator": "EQ",
        "value": "string"
      ]
    ],
    "search_from": 0,
    "search_to": 0
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/correlations/get")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/v1/correlations/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}",
  CURLOPT_HTTPHEADER => [
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/v1/correlations/get");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/correlations/get");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"extended_view\":true,\"filters\":[{\"field\":\"name\",\"operator\":\"EQ\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataobject

extended_viewboolean

filtersarray

An array of filter fields.

[

fieldobject (Enum)

Identifies the correlation rule field the filter is matching. Filters are based on the following keywords:

name: Correlation rule name.
severity: Correlation rule severity.
xql_query: Correlation rule XQL query.
is_enabled: Whether the correlation rule is enabled or disabled.
description: Correlation rule description.
alert_name: Alert name.
alert_category: Alert category.
alert_description: Alert description.
alert_fields: Alert fields.
execution_mode: Whether execution mode is scheduled or real time.
search_window: Amount of time for search window.
simple_schedule: Correlation rule schedule.
timezone: Correlation rule timezone.
crontab: Linux scheduling for correlation rule.
suppression_enabled: Whether suppression is enabled for correlation rule.
suppression_duration: Duration of correlation rule suppression.
suppression_fields: Suppration fields.
dataset: Correlation rule dataset.
user_defined_severity: User-defined severity.
user_defined_category: User-defined category.
mitre_defs: MITRE definitions.
investigation_query_link: Investigation query link.
drilldown_query_timeframe: Whether the drilldown query timeframe is query or alert.
mapping_strategy: Whether the mapping strategy is auto or custom.
alert_domain: Alert domain.

Allowed values:"name""severity""xql_query""is_enabled""descriptoin""alert_name""alert_category""alert_description""alert_fields""execution_mode""search_window""simple_schedule""timezone""crontab""suppression_enabled""suppression_duration""suppression_fields""dataset""user_defined_severity""user_defined_category""mitre_defs""investigation_query_link""drilldown_query_timeframe""mapping_strategy""alert_domain"

operatorobject (Enum)

Identifies the comparison operator you want to use for this filter. Valid keywords are: EQ / NEQ

name: String
severity: String
xql_query: String
is_enabled: Boolean
description: String
alert_name: String
alert_category: String
alert_description: String
alert_fields: String or dictionary
execution_mode: String
search_window: String
simple_schedule: String
timezone: String
crontab: String
suppression_enabled: Boolean
suppression_duration: String
dataset: String
user_defined_severity: String
user_defined_category: String
investigation_query_link: String
drilldown_query_timeframe: String
mapping_strategy: String
alert_domain: String IN
suppression_fields: List of strings
mitre_defs: List of strings

Allowed values:"EQ""NEQ""IN""GTE""LTE"

valuestring or boolean or array

Value that this filter must match. The contents of this field will differ depending on the correlation rule field that you specified for this filter:

name, xql_query, description, alert_name, alert_description, alert_fields, suppression_duration, dataset, user_defined_severity, user_defined_category, investigation_query_link: String.
severity: String, can be one of the following: SEV_010_INFO, SEV_020_LOW, SEV_030_MEDIUM, SEV_040_HIGH
is_enabled: String, can be one of the following: enabled or disabled.
alert_category: String, can be one of the following: other, persistence, evasion, tampering, file_type_obfuscation, privilege_escalation, credential_access, lateral_movement, execution, collection, exfiltration, infiltration, dropper, file_privilege_manipulation, reconnaissance, discovery.
alert_fields: Dictionary.
execution_mode: String, can be one of the following: scheduled or real_time.
search_window: String, for example: "2 hours".
simple_schedule: String, for example: "5 minutes".
timezone: String, for example: "Asia/Jerusalem".
crontab: String, for example: "*/10 * * * *".
suppression_enabled: Boolean: true or false.
suppression_fields: List of strings.
mitre_defs: List of strings or dictionary.
drilldown_query_timeframe: String, can be one of the following: query or alert.
mapping_strategy: String, can be one of the following: auto or custom.
alert_domain: String, can be one of the following: domain_security, domain_it, domain_hunting.

]

search_frominteger

Integer representing the starting offset within the query result set from which you want correlation rules returned. Correlation rules are returned as a zero-based list. Any correlation rule indexed less than this value is not returned in the final result set and defaults to zero.

search_tointeger

Integer representing the end offset within the result set after which you do not want BIOCs returned. BIOCs in the BIOC list that are indexed higher than this value are not returned in the final results set. Defaults to >100, which returns all BIOCs to the end of the list.

REQUEST

{
  "request_data": {
    "extended_view": false
  }
}

Responses

Body

application/json

objects_countinteger

objectsarray

[

idinteger

namestring

severitystring

xql_querystring

is_enabledstring

descriptionstring

alert_namestring

alert_categorystring

alert_fieldsobject

execution_modestring

search_windowstring

simple_schedulestring

timezonestring

crontabstring

suppression_enabledboolean

suppression_fieldsarray[string]

datasetstring

mitre_defsobject

TA0005 - Defense Evasionarray[string]

drilldown_query_timeframestring

mapping_strategystring

]

objects_typestring

RESPONSE

{
  "objects_count": 2,
  "objects": [
    {
      "id": 1,
      "name": "Test",
      "severity": "SEV_040_HIGH",
      "xql_query": "dataset = xdr_data | filter event_type = 1",
      "is_enabled": "DISABLED",
      "description": "",
      "alert_name": "Test",
      "alert_category": "User Defined",
      "alert_description": null,
      "alert_fields": {
        "agent_hostname": null,
        "action_local_ip": null,
        "action_remote_ip": null,
        "action_remote_port": null,
        "agent_device_domain": null,
        "actor_effective_username": null,
        "actor_process_image_name": null,
        "actor_process_image_path": null,
        "actor_process_command_line": null,
        "actor_process_image_sha256": null
      },
      "execution_mode": "SCHEDULED",
      "search_window": "10 minutes",
      "simple_schedule": "10 minutes",
      "timezone": "Asia/Jerusalem",
      "crontab": "*/10 * * * *",
      "suppression_enabled": false,
      "suppression_duration": null,
      "suppression_fields": null,
      "dataset": "alerts",
      "user_defined_severity": null,
      "user_defined_category": "event_type",
      "mitre_defs": {},
      "investigation_query_link": null,
      "drilldown_query_timeframe": "ALERT",
      "mapping_strategy": "AUTO"
    },
    {
      "id": 28,
      "name": "AnotherTest",
      "severity": "SEV_030_MEDIUM",
      "xql_query": "dataset = xdr_data | fields event_type, action_process_username, uuid, action_boot_time  | comp values(*) as * by action_process_username\n",
      "is_enabled": "ENABLED",
      "description": "Some description",
      "alert_name": "Test Alert",
      "alert_category": "DISCOVERY",
      "alert_description": "Test",
      "alert_fields": {},
      "execution_mode": "SCHEDULED",
      "search_window": "1 hours",
      "simple_schedule": "10 minutes",
      "timezone": "Asia/Jerusalem",
      "crontab": "*/10 * * * *",
      "suppression_enabled": true,
      "suppression_duration": "1 hours",
      "suppression_fields": [
        "event_type"
      ],
      "dataset": "alerts",
      "user_defined_severity": null,
      "user_defined_category": null,
      "mitre_defs": {
        "TA0005 - Defense Evasion": [
          "T1014 - Rootkit"
        ]
      },
      "investigation_query_link": "dataset = xdr_data | fields event_type, action_process_username, uuid, action_boot_time  | comp values(*) as * by action_process_username",
      "drilldown_query_timeframe": "ALERT",
      "mapping_strategy": "CUSTOM"
    }
  ],
  "objects_type": "correlations"
}

Bad Request. Got invalid JSON.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. User does not have the required license type to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Internal server error. A unified status for API communication type errors.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}