Set an Endpoint Alias

post /public_api/v1/endpoints/update_agent_name

Set or modify an Alias field for your endpoints.

Required license: Cortex XSIAM Premium or Cortex XSIAM Enterprise. In Cortex NG SIEM, requires endpoints or the Cortex Cloud Runtime Security add-on.

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/endpoints/update_agent_name'
    
      -d
      ''

import http.client

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

payload = "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}"

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

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

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\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}"

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

const data = JSON.stringify({
  "request_data": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": [
          "string"
        ]
      }
    ],
    "alias": "string"
  }
});

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/endpoints/update_agent_name");
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/endpoints/update_agent_name")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "filters": [
      [
        "field": "endpoint_id_list",
        "operator": "in",
        "value": ["string"]
      ]
    ],
    "alias": "string"
  ]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/endpoints/update_agent_name")! 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/endpoints/update_agent_name",
  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\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}",
  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/endpoints/update_agent_name");

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\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/endpoints/update_agent_name");
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\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":[\"string\"]}],\"alias\":\"string\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataobject

filtersarray

An array of filter fields.

[

fieldstring (Enum)required

String that identifies the field the filter is matching. Filters are based on the following keywords:

endpoint_id_list: List of endpoint IDs.
endpoint_status: Status of the endpoint ID.
dist_name: Distribution / Installation Package name.
ip_list: List of IP addresses.
group_name: Group name the agent belongs to.
platform: Platform name.
alias: Alias name.
isolate: If the endpoint was isolated.
hostname: Hostname.
cloud_provider: Cloud provider (for example, AWS, GCP, Azure).
cloud_region: Cloud region where the endpoint is deployed.
cloud_provider_account_id: Cloud provider account ID.
cloud_instance_id: Cloud instance ID of the endpoint.
cloud_id: Cloud ID of the endpoint.

Allowed values:"endpoint_id_list""endpoint_status""dist_name""ip_list""group_name""platform""alias""isolate""hostname""cloud_provider""cloud_region""cloud_provider_account_id""cloud_instance_id""cloud_id"

operatorstring (Enum)required

String that identifies the comparison operator you want to use for this filter. Valid keywords and values are: in

endpoint_id_list, dist_name, group_name, alias, hostname, username: List of strings.
endpoint_status: Permitted values are connected or disconnected
ip_list: List of strings, for example 192.168.5.12.
platform: Permitted values are windows, linux, macos, or android
isolate: Permitted values are isolated or unisolated.
scan_status: Permitted values are none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error. gte / lte
first_seen and last_seen: Integer in timestamp epoch milliseconds.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

Allowed values:"in""gte""lte"

valueobjectrequired

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

endpoint_id_list, dist_name, hostname, alias, group_name: List of strings.
endpoint_status: Must contain only the following valid values: connected or disconnected
ip_list: String list of IP addresses.
platform: Must contain only the following valid values: windows, linux, macos, or android.
isolate: Must contain only the following valid values: isolated or unisolated.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

One of

Array

string

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

endpoint_id_list, dist_name, hostname, alias, group_name: List of strings.
endpoint_status: Must contain only the following valid values: connected or disconnected
ip_list: String list of IP addresses.
platform: Must contain only the following valid values: windows, linux, macos, or android.
isolate: Must contain only the following valid values: isolated or unisolated.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

]

aliasstring

The alias name you want to set or modify.

Note: If you send an empty field, the current alias name is deleted.

REQUESTexample-1
{
  "request_data": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": [
          "<distribution_id>"
        ]
      }
    ],
    "alias": "<alias_name>"
  }
}

Responses

Successful response

Body

application/json

true=The alias name was set or modified successfully.

boolean

true=The alias name was set or modified successfully.

RESPONSE
false

Bad Request. Got an 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"
}