Scan Endpoints

Cortex XDR REST API
post /public_api/v1/endpoints/scan

Run a scan on selected endpoints. - Response is concatenated using AND condition (OR is not supported). - Offset is the zero-based number of incidents from the start of the result set.

Required license: Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per GB

CURL
curl -X POST \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ "https://api-yourfqdn/public_api/v1/endpoints/scan" \ -d '{ "request_data" : { "incident_id" : "incident_id", "filters" : [ { "field" : "field", "value" : [ "value", "value" ], "operator" : "in" }, { "field" : "field", "value" : [ "value", "value" ], "operator" : "in" } ] } }'
Request
Body
optional
Note: You can send a request to retrieve either all or filtered results.
Example: {"request_data":{"filters":"all"}}
request_data
required
A dictionary containing the API request fields.
filters
required
Array (Enum)
An array of filter fields. To scan all endpoints, use the value all.
Allowed values:
all
field
required
String

String that identifies a list the filters match. Filters are based on the following keywords:

  • endpoint_id_list: List of endpoint IDs.
  • dist_name: Name of the distribution list.
  • first_seen: When an endpoint was first seen.
  • last_seen: When an endpoint was last seen.
  • ip_list: List of IP addresses.
  • group_name: Name of endpoint group.
  • platform: Type of operating system.
  • alias: Endpoint alias name.
  • isolate: If an endpoint has been isolated.
  • hostname: Name of host.
operator
required
String (Enum)

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
  • ip_list: List of strings, for example 192.168.5.12
  • platform: Permitted values are windows, linux, macos, 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.
Allowed values:
in
gte
lte
value
required
Array of strings

Value that this filter must match. Valid keywords:

  • first_seen, last_seen: Integer representing the number of milliseconds after the Unix epoch, UTC timezone.
  • endpoint_id_list, dist_name, hostname, alias, group_name: List of strings
  • ip_list: Must contain an IP address string
  • isolate: Must be isolated or unisolated.
  • platform: Must be either windows, linux, macos, or android.
incident_id
optional
String
Incident ID. When included in the request, the Scan Endpoints action will appear in the Cortex XDR Incident View Timeline tab.
Responses

Successful response

Body
reply
optional
JSON object containing the query result.
action_id
optional
String

ID of action to scan selected endpoints. Response only indicates the request was successfully sent to the endpoint. To track if the scan was successful either:

  • In Cortex XDR console, navigate to Response > Action Center > All Actions and search for the action ID. Make sure the Action ID field is selected in the table Layout settings.
  • Send a Get Action Status API request.
endpoints_count
optional
String
Number of endpoints included in the request.

Bad Request. Got an invalid JSON.

Body
The query result upon error.
err_code
optional
String
HTTP response code.
err_msg
optional
String
Error message.
Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
err_extra
optional
String
Additional information describing the error.

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

Body
The query result upon error.
err_code
optional
String
HTTP response code.
err_msg
optional
String
Error message.
Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
err_extra
optional
String
Additional information describing the error.

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

Body
The query result upon error.
err_code
optional
String
HTTP response code.
err_msg
optional
String
Error message.
Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
err_extra
optional
String
Additional information describing the error.

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

Body
The query result upon error.
err_code
optional
String
HTTP response code.
err_msg
optional
String
Error message.
Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
err_extra
optional
String
Additional information describing the error.

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

Body
The query result upon error.
err_code
optional
String
HTTP response code.
err_msg
optional
String
Error message.
Example: {"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
err_extra
optional
String
Additional information describing the error.