Insert or update Correlation Rules

post /public_api/v1/correlations/insert

Insert new Correlation Rules or update existing Correlation Rules.

Note: The Correlation Rule id is tenant specific and can't be used across tenants. Inserting Correlation Rules with the same id as an existing Correlation Rule on that tenant will overwrite the existing Correlation Rule.

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/insert'
    
      -d
      ''

import http.client

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

payload = "{\"request_data\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}"

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

conn.request("POST", "/public_api/v1/correlations/insert", 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/insert")

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\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}"

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

const data = JSON.stringify({
  "request_data": [
    {
      "rule_id": 0,
      "name": "string",
      "severity": "SEV_010_INFO",
      "xql_query": "string",
      "is_enabled": true,
      "description": "string",
      "alert_name": "string",
      "alert_category": "OTHER",
      "alert_description": "string",
      "alert_fields": {
        "property1": null,
        "property2": null
      },
      "execution_mode": "SCHEDULED",
      "search_window": "\"2 hours\"",
      "simple_schedule": "\"5 minutes\"",
      "timezone": "\"Asia/Jerusalem\"",
      "crontab": "\"*/10 * * * *\"",
      "suppression_enabled": true,
      "suppression_duration": "\"1 hours\"",
      "suppression_fields": [
        "\"event_type\""
      ],
      "dataset": "string",
      "user_defined_severity": "string",
      "user_defined_category": "string",
      "mitre_defs": {
        "property1": null,
        "property2": null
      },
      "investigation_query_link": "string",
      "drilldown_query_timeframe": "QUERY",
      "mapping_strategy": "AUTO"
    }
  ]
});

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/insert");
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/insert")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    [
      "rule_id": 0,
      "name": "string",
      "severity": "SEV_010_INFO",
      "xql_query": "string",
      "is_enabled": true,
      "description": "string",
      "alert_name": "string",
      "alert_category": "OTHER",
      "alert_description": "string",
      "alert_fields": [
        "property1": ,
        "property2": 
      ],
      "execution_mode": "SCHEDULED",
      "search_window": "\"2 hours\"",
      "simple_schedule": "\"5 minutes\"",
      "timezone": "\"Asia/Jerusalem\"",
      "crontab": "\"*/10 * * * *\"",
      "suppression_enabled": true,
      "suppression_duration": "\"1 hours\"",
      "suppression_fields": ["\"event_type\""],
      "dataset": "string",
      "user_defined_severity": "string",
      "user_defined_category": "string",
      "mitre_defs": [
        "property1": ,
        "property2": 
      ],
      "investigation_query_link": "string",
      "drilldown_query_timeframe": "QUERY",
      "mapping_strategy": "AUTO"
    ]
  ]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/correlations/insert")! 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/insert",
  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\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}",
  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/insert");

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\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/correlations/insert");
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\":[{\"rule_id\":0,\"name\":\"string\",\"severity\":\"SEV_010_INFO\",\"xql_query\":\"string\",\"is_enabled\":true,\"description\":\"string\",\"alert_name\":\"string\",\"alert_category\":\"OTHER\",\"alert_description\":\"string\",\"alert_fields\":{\"property1\":null,\"property2\":null},\"execution_mode\":\"SCHEDULED\",\"search_window\":\"\\\"2 hours\\\"\",\"simple_schedule\":\"\\\"5 minutes\\\"\",\"timezone\":\"\\\"Asia/Jerusalem\\\"\",\"crontab\":\"\\\"*/10 * * * *\\\"\",\"suppression_enabled\":true,\"suppression_duration\":\"\\\"1 hours\\\"\",\"suppression_fields\":[\"\\\"event_type\\\"\"],\"dataset\":\"string\",\"user_defined_severity\":\"string\",\"user_defined_category\":\"string\",\"mitre_defs\":{\"property1\":null,\"property2\":null},\"investigation_query_link\":\"string\",\"drilldown_query_timeframe\":\"QUERY\",\"mapping_strategy\":\"AUTO\"}]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataarrayrequired

[

rule_idinteger

namestring

Correlation rule name.

severityobject (Enum)

Correlation rule severity.

Allowed values:"SEV_010_INFO""SEV_020_LOW""SEV_030_MEDIUM""SEV_040_HIGH"

xql_querystring

Correlation rule XQL query.

is_enabledboolean

Whether the correlation rule is enabled or disabled.

descriptionstring

Correlation rule description.

alert_namestring

Alert name.

alert_categoryobject (Enum)

Alert category.

Allowed values:"OTHER""PERSISTENCE""EVASION""TAMPERING""FILE_TYPE_OBFUSCATION""PRIVILEGE_ESCALATION""CREDENTIAL_ACCESS""LATERAL_MOVEMENT""EXECUTION""COLLECTION""EXFILTRATION""INFILTRATION""DROPPER""FILE_PRIVILEGE_MANIPULATION""RECONNAISSANCE""DISCOVERY"

alert_descriptionstring

Alert description.

alert_fieldsobject

Alert fields.

Additional propertiesobject

execution_modeobject (Enum)

Correlation rule execution mode.

Allowed values:"SCHEDULED""REAL_TIME"

search_windowstring

Search window.

Example:"\"2 hours\""

simple_schedulestring

Correlation rule simple schedule.

Example:"\"5 minutes\""

timezonestring

Correlation rule timezone.

Example:"\"Asia/Jerusalem\""

crontabstring

Linux scheduling for correlation rule.

Example:"\"*/10 * * * *\""

suppression_enabledboolean

suppression_durationstring

Example:"\"1 hours\""

suppression_fieldsarray[string]

datasetstring

user_defined_severitystring

user_defined_categorystring

mitre_defsobject

Additional propertiesobject

investigation_query_linkstring

drilldown_query_timeframeobject (Enum)

Allowed values:"QUERY""ALERT"

mapping_strategyobject (Enum)

Allowed values:"AUTO""CUSTOM"

]

REQUESTExample 1
{
  "request_data": [
    {
      "rule_id": 28,
      "name": "Test",
      "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": "true",
      "description": "RTESRTESTestret",
      "alert_name": "Test",
      "alert_category": "DISCOVERY",
      "alert_description": "Test",
      "alert_fields": {},
      "execution_mode": "REAL_TIME",
      "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": "AUTO"
    }
  ]
}

Responses

Body

application/json

added_objectsarray

List of Correlation Rule objects added.

[

idinteger

statusstring

]

updated_objectsarray

List of Correlation Rule objects updated.

[

idinteger

statusstring

]

errorsarray[string]

List of error messages, if there are any.

RESPONSEExample 1
{
  "added_objects": [],
  "updated_objects": [
    {
      "id": 28
    },
    {
      "status": "Updated the correlation rule with the ID: 28 successfully"
    }
  ],
  "errors": []
}

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"
}