{ "openapi": "3.0.0", "x-hideTryItPanel": true, "info": { "title": "Cortex XDR REST API", "description": "Using the Cortex XDR APIs, you can integrate Cortex XDR with third-party apps or services to ingest alerts and to leverage alert stitching and investigation capabilities. The APIs allows you to manage incidents in a ticketing or automation system of your choice by reviewing and editing the incident's details, status, and assignee. Using the APIs, you can also retrieve information on the endpoints, create installation package, perform response actions directly on the endpoint and more.\n\nVersion 3.18", "version": "3.18", "contact": { "email": "docs-cortex@paloaltonetworks.com", "name": "Cortex Documentation Team", "url": "https://cortex-docs.paloaltonetworks.com/p/XDR" } }, "servers": [ { "url": "https://api-yourfqdn" } ], "components": { "securitySchemes": { "api_key": { "name": "Authorization", "type": "apiKey", "in": "header" } }, "schemas": { "event": { "title": "event", "type": "object", "x-examples": { "example-1": { "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": "", "actor_process_image_path": "c:\\\\virus.exe", "actor_process_image_name": "virus.exe", "actor_process_command_line": "c:\\\\virus.exe", "actor_process_signature_status": "N/A", "actor_process_signature_vendor": null, "actor_process_image_sha256": "", "actor_process_image_md5": null, "actor_process_causality_id": null, "actor_causality_id": null, "actor_process_os_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 } }, "properties": { "agent_install_type": { "type": "string" }, "agent_host_boot_time": { "type": "integer" }, "event_sub_type": { "type": "string" }, "module_id": { "type": "string" }, "association_strength": { "type": "string" }, "dst_association_strength": { "type": "string" }, "story_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "event_timestamp": { "type": "integer" }, "actor_process_instance_id": { "type": "string" }, "actor_process_image_path": { "type": "string" }, "actor_process_image_name": { "type": "string" }, "actor_process_command_line": { "type": "string" }, "actor_process_signature_status": { "type": "string" }, "actor_process_signature_vendor": { "type": "string" }, "actor_process_image_sha256": { "type": "string" }, "actor_process_image_md5": { "type": "string" }, "actor_process_causality_id": { "type": "string" }, "actor_causality_id": { "type": "string" }, "actor_process_os_pid": { "type": "string" }, "actor_thread_thread_id": { "type": "string" }, "causality_actor_process_image_name": { "type": "string" }, "causality_actor_process_command_line": { "type": "string" }, "causality_actor_process_image_path": { "type": "string" }, "causality_actor_process_signature_vendor": { "type": "string" }, "causality_actor_process_signature_status": { "type": "string" }, "causality_actor_causality_id": { "type": "string" }, "causality_actor_process_execution_time": { "type": "integer" }, "causality_actor_process_image_md5": { "type": "string" }, "causality_actor_process_image_sha256": { "type": "string" }, "action_file_path": { "type": "string" }, "action_file_name": { "type": "string" }, "action_file_md5": { "type": "string" }, "action_file_sha256": { "type": "string" }, "action_file_macro_sha256": { "type": "string" }, "action_registry_data": { "type": "string" }, "action_registry_key_name": { "type": "string" }, "action_registry_value_name": { "type": "string" }, "action_registry_full_key": { "type": "string" }, "action_local_ip": { "type": "string" }, "action_local_port": { "type": "string" }, "action_remote_ip": { "type": "string" }, "action_remote_port": { "type": "string" }, "action_external_hostname": { "type": "string" }, "action_country": { "type": "string" }, "action_process_instance_id": { "type": "string" }, "action_process_causality_id": { "type": "string" }, "action_process_image_name": { "type": "string" }, "action_process_image_sha256": { "type": "string" }, "action_process_image_command_line": { "type": "string" }, "action_process_signature_status": { "type": "string" }, "action_process_signature_vendor": { "type": "string" }, "os_actor_effective_username": { "type": "string" }, "os_actor_process_instance_id": { "type": "string" }, "os_actor_process_image_path": { "type": "string" }, "os_actor_process_image_name": { "type": "string" }, "os_actor_process_command_line": { "type": "string" }, "os_actor_process_signature_status": { "type": "string" }, "os_actor_process_signature_vendor": { "type": "string" }, "os_actor_process_image_sha256": { "type": "string" }, "os_actor_process_causality_id": { "type": "string" }, "os_actor_causality_id": { "type": "string" }, "os_actor_process_os_pid": { "type": "string" }, "os_actor_thread_thread_id": { "type": "string" }, "fw_app_id": { "type": "string" }, "fw_interface_from": { "type": "string" }, "fw_interface_to": { "type": "string" }, "fw_rule": { "type": "string" }, "fw_rule_id": { "type": "string" }, "fw_device_name": { "type": "string" }, "fw_serial_number": { "type": "integer" }, "fw_url_domain": { "type": "string" }, "fw_email_subject": { "type": "string" }, "fw_email_sender": { "type": "string" }, "fw_email_recipient": { "type": "string" }, "fw_app_subcategory": { "type": "string" }, "fw_app_category": { "type": "string" }, "fw_app_technology": { "type": "string" }, "fw_vsys": { "type": "string" }, "fw_xff": { "type": "string" }, "fw_misc": { "type": "string" }, "fw_is_phishing": { "type": "string" }, "dst_agent_id": { "type": "string" }, "dst_causality_actor_process_execution_time": { "type": "integer" }, "dns_query_name": { "type": "string" }, "dst_action_external_hostname": { "type": "string" }, "dst_action_country": { "type": "string" }, "dst_action_external_port": { "type": "string" }, "user_name": { "type": "string" } } }, "alert": { "title": "alert", "type": "object", "x-examples": { "example-1": { "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_device_domain": null, "agent_fqdn": "test", "agent_os_type": "Windows", "agent_os_sub_type": "", "agent_data_collection_status": true, "mac": null, "mac_address": [ "" ], "agent_is_vdi": null, "contains_featured_host": "NO", "contains_featured_user": "NO", "contains_featured_ip": "NO", "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": "", "actor_process_image_path": "c:\\\\virus.exe", "actor_process_image_name": "virus.exe", "actor_process_command_line": "c:\\\\virus.exe", "actor_process_signature_status": "N/A", "actor_process_signature_vendor": null, "actor_process_image_sha256": "", "actor_process_image_md5": null, "actor_process_causality_id": null, "actor_causality_id": null, "actor_process_os_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": "", "detection_timestamp": 1603279888980, "name": "Kernel Privilege Escalation", "category": "Exploit", "endpoint_id": "", "description": "Local privilege escalation prevented", "host_ip": [ "" ], "host_name": "Test", "source": "XDR Agent", "action": "BLOCKED", "action_pretty": "Prevented (Blocked)" } }, "x-internal": false, "properties": { "external_id": { "type": "string" }, "severity": { "type": "string" }, "matching_status": { "type": "string" }, "end_match_attempt_ts": { "type": "integer" }, "local_insert_ts": { "type": "integer" }, "bioc_indicator": { "type": "string" }, "matching_service_rule_id": { "type": "string" }, "attempt_counter": { "type": "integer" }, "bioc_category_enum_key": { "type": "string" }, "is_whitelisted": { "type": "boolean" }, "starred": { "type": "boolean" }, "deduplicate_tokens": { "type": "string" }, "filter_rule_id": { "type": "string" }, "mitre_technique_id_and_name": { "type": "array", "items": { "type": "string" } }, "mitre_tactic_id_and_name": { "type": "array", "items": { "type": "string" } }, "agent_version": { "type": "string" }, "agent_device_domain": { "type": "string" }, "agent_fqdn": { "type": "string" }, "agent_os_type": { "type": "string" }, "agent_os_sub_type": { "type": "string" }, "agent_data_collection_status": { "type": "boolean" }, "mac": { "type": "string" }, "mac_address": { "type": "array", "items": { "type": "string" } }, "agent_is_vdi": { "type": "boolean" }, "contains_featured_host": { "type": "string", "enum": [ "YES", "NO" ] }, "contains_featured_user": { "type": "string", "enum": [ "YES", "NO" ] }, "contains_featured_ip": { "type": "string", "enum": [ "YES", "NO" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/event" } }, "alert_id": { "type": "string" }, "detection_timestamp": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string" }, "endpoint_id": { "type": "string" }, "description": { "type": "string" }, "host_ip": { "type": "array", "items": { "type": "string" } }, "host_name": { "type": "string" }, "source": { "type": "string" }, "action": { "type": "string" }, "action_pretty": { "type": "string" } } }, "reply": { "title": "reply", "type": "object", "description": "The query result upon error.", "properties": { "err_code": { "type": "string", "description": "HTTP response code." }, "err_msg": { "type": "string", "description": "Error message.", "example": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}" }, "err_extra": { "type": "string", "description": "Additional information describing the error." } } }, "violation": { "title": "violation", "type": "object", "properties": { "hostname": { "type": "string" }, "username": { "type": "string" }, "ip": { "type": "string" }, "timestamp": { "type": "integer" }, "violation_id": { "type": "integer" }, "type": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor": { "type": "string" }, "product_id": { "type": "string" }, "product": { "type": "string" }, "serial": { "type": "string" }, "endpoint_id": { "type": "string" } }, "x-examples": { "example-1": { "hostname": "", "username": "test", "ip": "", "timestamp": 1576260019000, "violation_id": 11, "type": "Disk Drive", "vendor_id": "", "vendor": "", "product_id": "", "product": "", "serial": "", "endpoint_id": "" } } }, "GetProfilesRequestData": { "title": "GetProfilesRequestData", "type": "object", "description": "Parameters for the `get_profiles` call", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "prevention", "extension" ], "description": "The category of profiles to retrieve.\n- `prevention` – standard endpoint prevention profiles managed by\n `ProfilesService` (malware, exploit, restrictions, agent-settings,\n exceptions, etc.)\n- `extension` – device-control and host-firewall profiles managed by\n `DeviceControlProfilesService`\n", "example": "prevention" }, "profile_ids": { "type": "array", "description": "Optional list of profile IDs to filter by.\nWhen omitted or `null`, all profiles of the requested type are returned.\nWhen provided, only profiles whose `id` is in this list are returned.\nMust be a JSON array; passing a non-array value yields HTTP 400.\n", "items": { "type": "integer", "format": "int64", "example": 1, "nullable": true } } } }, "GetProfilesResponse": { "title": "GetProfilesResponse", "type": "object", "description": "Successful response envelope", "properties": { "reply": { "type": "array", "description": "List of matching profile objects.", "items": { "$ref": "#/components/schemas/ProfileObject" } } }, "x-examples": { "Example 1": { "reply": [ { "id": 1, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Default Malware Profile", "type": "MALWARE", "platform": "AGENT_OS_WINDOWS", "is_default": true, "is_global": false, "is_disabled": false, "associated_targets": [ "All endpoints" ], "usage_count": 5, "description": "Default anti-malware profile for Windows", "created_by": "system", "created_by_pretty": "Palo Alto Networks", "creation_time": 1700000000000, "modified_by": "admin@example.com", "modified_by_pretty": "Admin User", "modification_time": 1710000000000, "modules": { "malware": { "mode": "prevent" } } }, { "id": 2, "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Custom Exploit Profile", "type": "EXPLOIT", "platform": "AGENT_OS_MAC", "is_default": false, "is_global": false, "is_disabled": false, "associated_targets": [ "macOS Servers" ], "usage_count": 2, "description": null, "created_by": "admin@example.com", "created_by_pretty": "Admin User", "creation_time": 1705000000000, "modified_by": "admin@example.com", "modified_by_pretty": "Admin User", "modification_time": 1705000000000, "modules": {} } ] } } }, "ProfileObject": { "title": "ProfileObject", "type": "object", "description": "A single endpoint security profile.\n\n**Note**: The fields `is_in_user_scope` and `at_risk` exist in the internal data model but are **always stripped** before the API response is returned and will never appear in the output.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Internal numeric profile ID", "example": 1 }, "uuid": { "type": "string", "description": "Globally unique profile identifier (UUID v4)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Human-readable profile name.", "example": "Default Malware Profile" }, "type": { "type": "string", "description": "Target operating system", "enum": [ "AGENT_OS_WINDOWS", "AGENT_OS_MAC", "AGENT_OS_LINUX", "AGENT_OS_ANDROID", "AGENT_OS_IOS", "AGENT_OS_CAAS_LINUX", "AGENT_OS_SERVERLESS" ], "example": "AGENT_OS_WINDOWS" }, "is_default": { "type": "boolean", "description": "Whether this is the system-managed default profile for its type and OS", "example": true }, "is_global": { "type": "boolean", "description": "Whether this profile is a global (cross-tenant) profile", "example": false }, "is_disabled": { "type": "boolean", "description": "Whether this profile is currently disabled", "example": false }, "associated_targets": { "type": "array", "description": "Human-readable list of policy rule targets (endpoint groups, tags, and so on.) that reference this profile, rendered as UI-friendly strings.\n`null` when the profile is not referenced by any policy rule.\n", "items": { "type": "string", "example": "Windows Servers", "nullable": true } }, "usage_count": { "type": "integer", "description": "Number of policy rules that reference this profile", "example": 5, "format": "int32", "nullable": true }, "description": { "type": "string", "description": "Optional free-text description of the profile", "example": "Default anti-malware profile for Windows endpoints", "nullable": true }, "created_by": { "type": "string", "example": "admin@example.com", "description": "Internal identifier (email or system name) of the creator", "nullable": true }, "created_by_pretty": { "type": "string", "description": "Display name of the creator", "example": "Admin User", "nullable": true }, "creation_time": { "type": "integer", "format": "int64", "description": "Profile creation timestamp in Unix epoch milliseconds", "example": 1700000000000, "nullable": true }, "modified_by": { "type": "string", "example": "admin@example.com", "description": "Internal identifier of the last modifier", "nullable": true }, "modified_by_pretty": { "type": "string", "example": "Admin User", "description": "Display name of the last modifier", "nullable": true }, "modification_time": { "type": "integer", "format": "int64", "description": "Last modification timestamp in Unix epoch milliseconds", "example": 1710000000000, "nullable": true }, "modules": { "type": "object", "description": "JSON object containing the profile's security module configuration.\nThe schema varies by `type` and `platform`. Common top-level keys\nare module names (for example, `malware`, `exploit`, `agent_settings`), \neach containing mode and sub-option settings.\n", "nullable": true, "example": { "malware": { "mode": "prevent", "scan_network_drives": false } } } }, "x-examples": {} }, "GetLegacyExceptionDataRequest": { "type": "object", "description": "Request body containing pagination, sorting, and filtering parameters for fetching legacy exception rules.", "x-examples": { "Example 1": { "request_data": { "search_from": 0, "search_to": 10, "sort": { "field": "id", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "ENABLED" }, { "field": "platform", "operator": "eq", "value": "Windows" }, { "field": "module", "operator": "in", "value": [ 1, 43 ] } ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "description": "Request body containing pagination, sorting, and filtering parameters.", "properties": { "search_from": { "type": "integer", "description": "Starting index for pagination (zero-based). Defines the offset from which to begin returning results.", "default": 0, "example": 0, "minimum": 0 }, "search_to": { "type": "integer", "description": "Ending index for pagination (exclusive). Defines the maximum number of results to return (search_to - search_from).", "minimum": 1, "default": 100, "example": 1 }, "sort": { "type": "object", "description": "Defines sorting criteria for query results.", "required": [ "field", "keyword" ], "properties": { "field": { "type": "string", "description": "Field name to sort by. For example, `id`, `rule_name`, `platform`, `modification_time`, `status`, and `user_email`.", "example": "id" }, "keyword": { "type": "string", "description": "Determines the sort order.", "enum": [ "asc", "desc" ], "example": "desc" } } }, "filters": { "type": "array", "description": "List of filter conditions. Multiple filters are combined with AND logic.", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "The field name to filter on. For example, `id`, `rule_name`, `platform`, `status`, `created_by`, `user_email`, `module` and `profile_ids`.", "example": "id" }, "operator": { "type": "string", "description": "The comparison operator. Most fields support `eq` operator. The `module` and `profile_ids` fields support `in` operator.", "example": "eq" }, "value": { "description": "The value to compare against. Type should match the field type.\nCan be a string or number depending on the operator.\n**Examples:**\n* If the `field` is `status`, the `value` can be `ENABLED` or `DISABLED`\n* If the `field` is `platform`, the `value` can be a string such as `Windows`, `macOS`, or `Linux`", "oneOf": [ { "type": "string" }, { "type": "integer" } ] } } } } } } } }, "AddLegacyExceptionDataRequest": { "type": "object", "description": "Request body for creating a legacy exception rule.", "x-internal": false, "required": [ "name", "platform", "module", "profile_ids", "status", "scope", "conditions" ], "properties": { "name": { "type": "string", "description": "Name for the legacy exception rule.", "minLength": 1, "maxLength": 128 }, "platform": { "type": "string", "description": "Target platform for the exception. Must be one of the platforms supported by the chosen module (see [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint response).", "example": "Windows" }, "module": { "type": "integer", "description": "Numeric ID of the protection module to create the exception for. Get valid module IDs from [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint.", "minimum": 1, "example": 1 }, "profile_ids": { "type": "array", "description": "List of prevention profile IDs this exception rule applies to. Use [/public_api/v1/endpoints/get_profiles](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-endpoints-get_profiles) endpoint to find existing profile IDs.\n- For `scope: PROFILE`: provide one or more profile IDs (e.g. `[29]`)\n- For `scope: GLOBAL`: must be an empty array `[]`", "items": { "type": "integer" } }, "status": { "type": "string", "description": "Status of the rule.\nAllowed values: `ENABLED` or `DISABLED`." }, "scope": { "type": "string", "description": "Scope of the exception:\n- `PROFILE` — exception applies to specific prevention profiles listed in `profile_ids`\n- `GLOBAL` — exception applies globally; `profile_ids` must be `[]` and the module must be an **Exception**-type module" }, "description": { "type": "string", "description": "Optional description of the exception rule.", "nullable": true }, "conditions": { "type": "object", "description": "The conditions structure depends on the chosen `module`. Use [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint to get the `conditions_definition` for each module." } } }, "EditLegacyExceptionDataRequest": { "type": "object", "description": "Request body for editing or updating an existing legacy exception rule.", "required": [ "exception_id", "update_data" ], "properties": { "exception_id": { "type": "string", "description": "The ID of the legacy exception to edit. Corresponds to the `id` field returned by the fetch API." }, "update_data": { "type": "object", "required": [ "name", "platform", "module", "profile_ids", "status", "scope", "conditions" ], "properties": { "name": { "type": "string", "description": "Name for the legacy exception rule." }, "platform": { "type": "string", "description": "Target platform for the exception. Must be one of the platforms supported by the chosen module (see [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint response)." }, "module": { "type": "integer", "description": "Numeric ID of the protection module to create the exception for. Get valid module IDs from [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint." }, "profile_ids": { "type": "array", "description": "List of prevention profile IDs this exception rule applies to. Use [/public_api/v1/endpoints/get_profiles](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-endpoints-get_profiles) endpoint to find existing profile IDs.\n- For `scope: PROFILE`: provide one or more profile IDs (e.g. `[29]`)\n- For `scope: GLOBAL`: must be an empty array `[]`", "items": { "type": "integer" } }, "status": { "type": "string", "description": "Status of the rule.\nAllowed values: `ENABLED` or `DISABLED`." }, "scope": { "type": "string", "description": "Scope of the exception:\n- `PROFILE` — exception applies to specific prevention profiles listed in `profile_ids`\n- `GLOBAL` — exception applies globally; `profile_ids` must be `[]` and the module must be an **Exception**-type module" }, "description": { "type": "string", "description": "Optional description of the exception rule." }, "conditions": { "type": "object", "description": "The conditions structure depends on the chosen `module`. Use [/public_api/v1/legacy_exceptions/get_modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) endpoint to get the `conditions_definition` for each module." } } } } }, "GetPublicLegacyExceptionResponse": { "type": "object", "title": "Get Legacy Exception Response", "description": "A legacy exception record as returned by the fetch API.", "x-examples": { "Example 1": { "reply": { "DATA": [ { "id": "d9c06bfa3f9b45a7a0196244e68d181d", "rule_name": "Test Legacy Exception Rule 1", "platform": "Linux", "conditions": "Process Name = Another test process AND Modules = Disable Injection OR Process Name = Test process AND Modules = Child Process Protection", "module": 43, "module_name": "Exceptions > Process Exceptions", "description": "test rule 1", "generating_alert_id": null, "created_by": "John Doe", "modification_time": 1772111647000, "user_email": "john.doe@example.com", "status": "ENABLED", "profile_ids": [ 27 ], "associated_targets": [ "Any" ], "is_in_user_scope": true }, { "id": "0a2661779a2d4a87b051158ea47f0022", "rule_name": "Test Legacy Exception Rule 2", "platform": "Windows", "conditions": "Remote IP Address : 192.168.1.45", "module": 1, "module_name": "Malware > Respond to Malicious Causality Chains", "description": "test rule 2", "generating_alert_id": null, "created_by": "Jane Doe", "modification_time": 1772089294000, "user_email": "jane.doe@example.com", "status": "ENABLED", "profile_ids": [ 29 ], "associated_targets": [], "is_in_user_scope": true } ], "FILTER_COUNT": 2, "TOTAL_COUNT": 2 } } }, "properties": { "reply": { "type": "object", "properties": { "DATA": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the legacy exception rule.", "example": "d9c06bfa3f9b45a7a0196244e68d181d" }, "rule_name": { "type": "string", "description": "Name of the legacy exception rule." }, "platform": { "type": "string", "description": "Target platform for the exception rule." }, "conditions": { "type": "string", "description": "Human-readable string representation of the exception conditions. This is a display string only." }, "module": { "type": "integer", "description": "Numeric ID of the protection module this exception applies to.", "example": 43 }, "module_name": { "type": "string", "description": "Name of the protection module.", "example": "Exceptions > Process Exceptions" }, "description": { "type": "string", "description": "Optional description of the exception rule." }, "generating_alert_id": { "description": "ID of the alert that generated this exception, if applicable.", "nullable": true }, "created_by": { "type": "string", "description": "Name of the user or API key that created the legacy exception rule. **Note**: API-created exception rules show as \"Public API - \"." }, "modification_time": { "type": "integer", "description": "Unix timestamp in milliseconds of the last modification." }, "user_email": { "type": "string", "description": "Email of the user who created the exception. **Note**: API-created exceptions show `n/a`." }, "status": { "type": "string", "description": "Indicates the current status of the rule." }, "profile_ids": { "type": "array", "description": "List of prevention profile IDs this exception is scoped to. Empty array `[]` indicates a GLOBAL scope exception.", "items": { "type": "integer" } }, "associated_targets": { "type": "array", "description": "Describes the endpoint targeting scope of the exception.", "items": { "type": "string" } }, "is_in_user_scope": { "type": "boolean", "description": "Whether the exception is within the current user's RBAC scope." } } } }, "FILTER_COUNT": { "type": "integer", "description": "The number of rules returned in the current response after applying filters.", "example": 2 }, "TOTAL_COUNT": { "type": "integer", "description": "The total number of rules available that match the filter criteria, regardless of pagination.", "example": 2 } } } } }, "GetInjectionDataRequest": { "type": "object", "x-examples": { "Example 1": { "search_from": 0, "search_to": 10, "sort": { "field": "rule_id", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "active" } ] } }, "description": "Request body containing pagination, sorting, and filtering parameters.", "properties": { "search_from": { "type": "integer", "minimum": 0, "default": 0, "example": 0, "description": "Starting index for pagination (zero-based). Defines the offset from which to begin returning results." }, "search_to": { "type": "integer", "minimum": 1, "default": 100, "example": 1, "description": "Ending index for pagination (exclusive). Defines the maximum number of results to return (search_to - search_from)." }, "sort": { "$ref": "#/components/schemas/SortingInjectionRequest" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterInjectionRequest" } } } }, "SortingInjectionRequest": { "type": "object", "required": [ "field", "keyword" ], "properties": { "field": { "type": "string", "minLength": 1, "description": "The field name to filter on. For example, `rule_id`, `rule_name`, `status`,`platform`.", "example": "rule_id" }, "keyword": { "type": "string", "enum": [ "asc", "desc" ], "description": "Determines the sort order.", "example": "desc" } }, "description": "Defines sorting criteria for query results." }, "FilterInjectionRequest": { "type": "object", "description": "Define filter condition for querying data.", "x-examples": { "Example 1": { "field": "status", "operator": "eq", "value": "active" } }, "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "minLength": 1, "description": "The field name to filter on. For example, `rule_id`, `rule_name`, `status`,`platform`.", "example": "status" }, "operator": { "type": "string", "minLength": 1, "description": "Comparison operator to use for filtering. For example, (`eq` (equals), `neq` (not equals), `gte` (greater than or equal), `lte` (less than or equal), `contains` or `not_contains`)", "default": "eq" }, "value": { "type": "string", "description": "The value to compare against. Type should match the field type.\nCan be a string or number depending on the operator.\n**Examples:**\n* If the `field` is `status`, the `value` can be `active`, `disabled`, or `expired`\n* If the `field` is `platform`, the `value` can be a string such as `windows`, `macos`, or `linux` \n", "example": "active" } } }, "PublicGetInjectionDataResponse": { "type": "object", "x-examples": { "Response with multiple rules": { "reply": { "data": [ { "rule_id": "2672e5d5d7b8421fb74f94895e29cda8", "rule_name": "Protect Critical App", "description": "Disable injection prevention for critical business application", "platform": "windows", "status": "disabled", "expiration_time": 1770445053461, "process_name": "criticalapp.exe", "path": "C:\\Program Files\\CriticalApp\\criticalapp.exe", "created_by": "Public API - 241", "creation_time": 1770358653000, "is_global": true, "profile_ids": [] }, { "rule_id": "9133403bfc764080ad8909a6e05b6793", "rule_name": "Dev Environment Exception", "description": "Allow injection for development tools", "platform": "linux", "status": "active", "expiration_time": 1770446020254, "process_name": "node", "path": "/usr/bin/node", "created_by": "John Doe", "creation_time": 1770359620000, "is_global": false, "profile_ids": [ 97 ] } ], "filter_count": 4, "total_count": 6 } } }, "properties": { "reply": { "type": "object", "description": "Container object for the response data and metadata", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DisableInjectionRulePAPIObject" } }, "filter_count": { "type": "integer", "description": "The number of rules returned in the current response after applying filters.", "example": 4 }, "total_count": { "type": "integer", "description": "The total number of rules available that match the filter criteria, regardless of pagination.", "example": 6 } } } } }, "InjectionResponseString": { "type": "object", "properties": { "reply": { "type": "string", "example": "e35dcf2150b74d19ba354fbe871f978d", "description": "Returns the Disable Injection and Prevention Rule ID." } } }, "DisableInjectionResponseString": { "type": "object", "properties": { "reply": { "type": "string", "example": "The selected rules were disabled", "description": "Describes the success message." } } }, "DisableInjectionRulePAPIObject": { "type": "object", "description": "Array of Disable Injection and Prevention rule objects matching the query criteria.", "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the rule. Auto-generated upon rule creation and used for all subsequent operations.", "example": "24bd70bab9d94905aa18773de2555969" }, "rule_name": { "type": "string", "description": "Name of the rule.", "example": "Protect Critical App" }, "description": { "type": "string", "description": "Description of the rule's purpose and context. ", "example": "Disable injection prevention for critical business application" }, "platform": { "type": "string", "example": "windows", "description": "Target operating system to which the rule applies. For example: `windows`, `linux`, or `macos`." }, "status": { "type": "string", "description": "Current status of the rule. For example: `active`, `disabled`, or `expired`.\n- `active`: Rule is active and being applied\n- `disabled`: Rule is inactive and not being applied\n- `expired`: Rule has passed its expiration time", "example": "active" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (milliseconds) when the rule will expire.", "example": 1770445053461 }, "process_name": { "type": "string", "description": "Name of the process executable to which this rule applies. Should match the exact process name as it appears in the system.", "example": "criticalApp.exe" }, "path": { "type": "string", "description": "Full file system path to the process executable. " }, "created_by": { "type": "string", "description": "Name of the user or API key ID that created this rule.", "example": "John Doe" }, "creation_time": { "type": "integer", "format": "int64", "description": "Unix timestamp (milliseconds) when the rule was created.", "example": 1770358653000 }, "is_global": { "type": "boolean", "description": "Indicates whether the rule applies globally to all endpoints or only to specific profiles.\n- `true`: Rule applies to all endpoints in the tenant.\n- `false`: Rule applies only to endpoints in the specified `profile_ids`.", "default": false }, "profile_ids": { "type": "array", "description": "Array of profile IDs to which this rule applies. Only relevant when is_global is false. \n`null` or empty when `is_global` is `true`.", "nullable": true, "items": { "type": "integer", "example": 96 } } } }, "DisableInjectionAddRulePAPIRequest": { "type": "object", "description": "Request schema for creating a new Disable Injection and Prevention rule. All required fields must be provided to successfully create a rule.", "required": [ "rule_name", "description", "platform", "process_name", "path", "hours_to_expiration", "scope" ], "properties": { "rule_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Unique name for the new rule. Must be between 1-100 characters and should be descriptive of the rule's purpose.", "example": "Global Windows Exception" }, "description": { "type": "string", "maxLength": 500, "example": "Allow injection for trusted Windows application across all endpoints", "description": "Description explaining the purpose and context of this rule. Maximum 500 characters." }, "platform": { "type": "string", "enum": [ "windows", "linux", "macos" ], "description": "Target operating system to which the rule applies. " }, "process_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the process executable to protect. Must match the exact process name (1-100 characters).", "example": "trustedapp.exe" }, "path": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Full file system path to the process executable. Must be a valid path for the specified platform (1-1000 characters).", "example": "C:\\Program Files\\TrustedApp\\trustedapp.exe" }, "hours_to_expiration": { "type": "integer", "enum": [ 24, 48 ], "description": "Number of hours until the rule expires. After expiration, the rule will no longer be applied. For example, 24 hours." }, "profile_ids": { "type": "array", "description": "Array of profile IDs to which this rule should apply. \nRequired when `scope` is `profile`. Must be `null` or omitted when scope is `global`.", "nullable": true, "items": { "type": "integer", "default": 96 } }, "scope": { "type": "string", "enum": [ "global", "profile" ], "description": "Defines the application scope of the rule.\n- `global`: Rule applies to all endpoints all matching endpoints (by platform and agent version >= 7.9)\n- `profile`: Rule applies only to endpoints in the specified `profile_ids`" } } }, "DisableInjectionDisableRulesPAPIRequest": { "type": "object", "description": "Request schema for disabling one or more existing Disable Injection Prevention rules. Requires at least one valid rule ID.", "required": [ "rule_ids" ], "properties": { "rule_ids": { "type": "array", "minLength": 1, "description": "Array of rule IDs to disable. Must contain at least one valid rule ID.", "items": { "type": "string", "example": "24bd70bab9d94905aa18773de2555969" } } }, "x-examples": { "Example 1": { "rule_ids": [ "24bd70bab9d94905aa18773de2555969" ] } } }, "GetDataRequest": { "type": "object", "x-examples": { "Example 1": { "search_from": 0, "search_to": 100, "sort": { "field": "rule_id", "keyword": "asc" }, "filters": [ { "field": "status", "operator": "eq", "value": "enabled" } ] }, "Example 2": { "search_from": 0, "search_to": 100, "sort": { "field": "modification_time", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "enabled" }, { "field": "modification_time", "operator": "gte", "value": 1762870187000 } ] } }, "properties": { "search_from": { "type": "integer", "default": 0, "description": "Zero-based index of the first Disable Prevention rule to return. Used for pagination.", "minimum": 0 }, "search_to": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Index number of Disable Prevention rules to return starting from `search_from`." }, "sort": { "$ref": "#/components/schemas/SortingRequest" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterRequest" } } } }, "SortingRequest": { "type": "object", "required": [ "field", "keyword" ], "properties": { "field": { "type": "string", "description": "Rule attribute to apply the filter on. For example: `rule_id`, `status`, `modification_time`, `platform`).", "example": "rule_id" }, "keyword": { "type": "string", "enum": [ "asc", "desc" ], "description": "Determines the sort order." } }, "x-examples": { "Example 1": { "field": "rule_id", "keyword": "asc" } } }, "FilterRequest": { "type": "object", "x-examples": { "Example 1": { "field": "status", "operator": "eq", "value": "enabled" }, "Example 2": { "field": "platform", "operator": "eq", "value": "macos" }, "Example 3": { "field": "modification_time", "operator": "eq", "value": "1762870187000" } }, "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "Rule attribute to apply the filter on. For example: `rule_id`, `status`, `modification_time`, `platform`).", "example": "status" }, "operator": { "type": "string", "description": "Comparison operator used for filtering. For example, (`eq`, `neq`, `gte`, `lte`, `contains` or `not_contains`)", "default": "eq" }, "value": { "type": "object", "description": "The value to compare against the specified field. The expected data type and format depend on the field being filtered and the operator used.\n\n**Examples:**\n\n* If the `field` is `status`, the `value` can be `enabled` or `disabled`.\n* If the `field` is `modification_time`, the `value` should be a Unix timestamp in milliseconds (for example, **`1762870187000`**).\n* If the `field` is `platform`, the `value` can be a string such as `windows`, `macos`, or `linux`\n" } } }, "PublicGetDataResponse": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DisablePreventionRulePAPIObject" } }, "filter_count": { "type": "integer", "description": "The number of rules returned in the current response after applying filters." }, "total_count": { "type": "integer", "description": "The total number of rules available that match the filter criteria, regardless of pagination." } } } }, "x-examples": { "Example 1": { "reply": { "data": [ { "rule_id": "171a1ef6086945008ff80a7012807364", "rule_name": "My MAC DPR !~~", "description": "My DPR via PAPI", "platform": "macos", "conditions": { "path": "/*", "signer": "company.inc." }, "module_ids": [ 38, 55 ], "profile_ids": [ 96 ], "scope": "profile", "status": "enabled", "created_by": "John Doe", "user_email": "john.doe@mysite.com", "modification_time": 1764695763000, "associated_targets": [ "endpoint name != AFDSFDS" ] } ], "filter_count": 1, "total_count": 4 } } } }, "BaseResponseString": { "type": "object", "properties": { "reply": { "type": "string", "example": "330fc8dec96a4810af886af328e73264", "description": "Returns the Disable Prevention Rule ID." } } }, "DeleteResponseString": { "type": "object", "properties": { "reply": { "type": "string", "example": "1 rule was deleted.", "description": "Describes the result of the API operation." } } }, "BaseResponseArrayModules": { "type": "object", "properties": { "reply": { "type": "array", "items": { "$ref": "#/components/schemas/DisablePreventionModulePAPIObject" } } }, "x-examples": { "Example 1": { "reply": [ { "module_id": 1, "name": "DLL Security", "description": "Memory Corruption Exploit", "profile_type": "Exploit", "conditions_definition": { "properties": { "sign_thumbprint": { "type": "string", "description": "Certificate Thumbprint" }, "signer": { "type": "string", "description": "Signer Name" }, "hash": { "type": "string", "description": "Hash" }, "command": { "type": "string", "description": "Command Line" }, "path": { "type": "string", "description": "Files / Folders" } } } } ] } } }, "DisablePreventionRulePAPIObject": { "type": "object", "x-examples": { "Example 1": { "rule_id": "1bce99ee792e4f0682d7c9bde0aaf44e", "rule_name": "My Mac DPR", "description": "Data prevention rules for my mac", "platform": "macos", "conditions": { "hash": "3b7d28f7a6c1e9b0f4a5c2d9e8f1a0b6c7d4e5f8091a2b3c4d5e6f7a8b9c0d1", "path": "/*", "signer": "trusted company.inc", "command": "command line argument", "sign_thumbprint": "Certificate thumbprint" }, "module_ids": [ 38 ], "profile_ids": [ 96 ], "scope": "profile", "status": "enabled", "created_by": "John Doe", "user_email": "john.doe@example.com", "modification_time": 1764475578200, "associated_targets": [ "endpoint name != ASFDSFDS" ] } }, "properties": { "rule_id": { "type": "string", "description": "The unique identifier of the Disable Prevention rule.", "example": "1bce99ee792e4f0682d7c9bde0aaf44e" }, "rule_name": { "type": "string", "description": "Name of the Disable Prevention rule.", "example": "My Mac DPR" }, "description": { "type": "string", "description": "Description explaining the purpose and behavior of the rule.", "example": "Data prevention rules for my mac" }, "platform": { "type": "string", "description": "Indicates the operating system to which the rule applies. For example, `windows`, `linux`, or `macos`", "example": "macos" }, "conditions": { "type": "object", "description": "A combination of parameters configured during rule creation.", "properties": { "hash": { "type": "string", "description": "SHA256 hash", "example": "3b7d28f7a6c1e9b0f4a5c2d9e8f1a0b6c7d4e5f8091a2b3c4d5e6f7a8b9c0d1" }, "path": { "type": "string", "description": "Path to the required files or folders", "example": "/*" }, "signer": { "type": "string", "description": "Trusted signer", "example": "company.inc" }, "command": { "type": "string", "description": "Command line argument", "example": "hi" }, "sign_thumbprint": { "type": "string", "description": "Certificate thumbprint", "example": "Certificate thumbprint" } } }, "module_ids": { "type": "array", "description": "A list of module ids associated with the rule.", "items": { "type": "integer", "example": 38 } }, "profile_ids": { "type": "array", "description": "A list of profile ids to which the rule is applied.", "items": { "type": "integer", "example": 96 } }, "scope": { "type": "string", "description": "Specifies the scope of the rule, such as `global` (All endpoints) or `profile` (Exception profiles).", "example": "profile" }, "status": { "type": "string", "description": "Current state of the rule (for example, `enabled` or `disabled`).", "example": "enabled" }, "created_by": { "type": "string", "description": "Name of the user who created the rule.", "example": "John Doe" }, "user_email": { "type": "string", "description": "Email address of the user associated with the creation or last modification of the rule.", "example": "john.doe@example.com" }, "modification_time": { "type": "integer", "format": "int64", "description": "Timestamp when the rule was last modified.", "example": 1764475578200 }, "associated_targets": { "type": "array", "items": { "type": "string", "example": "endpoint name != ASFDSFDS" } } } }, "DisablePreventionGetModulesPAPIRequest": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string", "description": "Indicates the operating system to which the rule applies. For example, `windows`, `linux`, or `macos`." } }, "x-examples": { "Example 1": { "platform": "windows" } } }, "DisablePreventionModulePAPIObject": { "type": "object", "x-examples": { "Example 1": { "module_id": 1, "name": "DLL Security", "description": "Memory Corruption Exploit", "profile_type": "Exploit", "conditions_definition": { "properties": { "hash": { "type": "string", "description": "Hash" }, "path": { "type": "string", "description": "Files / Folders", "minLength": 1 }, "command": { "type": "string", "description": "Command Line", "minLength": 1 }, "signer": { "type": "string", "description": "Signer Name", "minLength": 1 }, "sign_thumbprint": { "type": "string", "description": "Certificate Thumbprint", "minLength": 1 } } }, "additionalProperties": false, "minProperties": 1 } }, "properties": { "module_id": { "type": "integer", "description": "Module ID associated with the rule.", "example": 1 }, "name": { "type": "string", "example": "DLL Security", "description": "Name of the security module." }, "description": { "type": "string", "description": "Description of the disable prevention rule.", "example": "Memory Corruption Exploit" }, "profile_type": { "type": "string", "description": "Type of security profile.", "example": "Exploit" }, "conditions_definition": { "type": "object", "description": "A combination of parameters configured during rule creation.", "properties": { "properties": { "type": "object", "properties": { "hash": { "type": "object", "description": "SHA256 hash", "properties": { "type": { "type": "string" }, "description": { "type": "string", "example": "Hash" } } }, "path": { "type": "object", "description": "Path to the required files or folders", "properties": { "type": { "type": "string" }, "description": { "type": "string", "example": "Files / Folders" }, "minLength": { "type": "integer", "example": 1 } } }, "command": { "type": "object", "description": "Command line argument", "properties": { "type": { "type": "string" }, "description": { "type": "string", "example": "Command Line" }, "minLength": { "type": "integer", "example": 1 } } }, "signer": { "type": "object", "description": "Trusted signer", "properties": { "type": { "type": "string" }, "description": { "type": "string", "example": "Signer Name" }, "minLength": { "type": "integer", "example": 1 } } }, "sign_thumbprint": { "type": "object", "description": "Certificate thumbprint", "properties": { "type": { "type": "string" }, "description": { "type": "string", "example": "Certificate Thumbprint" }, "minLength": { "type": "integer", "example": 1 } } } } } } }, "additionalProperties": { "type": "boolean" }, "minProperties": { "type": "integer", "example": 1 } } }, "DisablePreventionAddRulePAPIRequest": { "$ref": "#/components/schemas/DisablePreventionModifyRulePAPIRequestBase", "x-examples": { "Example 1": { "rule_name": "string", "description": "string", "platform": "string", "module_ids": [ 0 ], "conditions": { "hash": "string", "path": "string", "signer": "string", "command": "string", "sign_thumbprint": "string" }, "profile_ids": [ 0 ], "status": "string", "scope": "string" } } }, "DisablePreventionEditRulePAPIRequest": { "allOf": [ { "$ref": "#/components/schemas/DisablePreventionModifyRulePAPIRequestBase" }, { "type": "object", "required": [ "rule_id" ], "properties": { "rule_id": { "type": "string", "description": "The unique identifier of the Disable Prevention rule.", "example": "5bfb2a15ca2a4525a4e69f11792dfe61" } } } ], "x-examples": { "Example 1": { "rule_name": "MAC DPR", "description": "Data Prevention rule for MAC.", "platform": "macos", "module_ids": [ 38, 55 ], "conditions": { "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 ", "path": "/*", "signer": "Trusted comapany.Inc", "command": "command line argument", "sign_thumbprint": "certificate thumbprint" }, "profile_ids": [ 97 ], "status": "enabled", "scope": "profile", "rule_id": "5bfb2a15ca2a4525a4e69f11792dfe61" } } }, "DisablePreventionModifyRulePAPIRequestBase": { "type": "object", "required": [ "rule_name", "description", "platform", "module_ids", "conditions", "status", "scope" ], "properties": { "rule_name": { "type": "string", "minLength": 1, "maxLength": 700, "description": "Name of the disable prevention rule." }, "description": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Description explaining the purpose and behavior of the rule." }, "platform": { "type": "string", "description": "Indicates the operating system to which the rule applies. For example, `windows`, `linux`, or `macos`" }, "module_ids": { "type": "array", "minLength": 1, "description": "A list of module ids associated with the rule.", "items": { "type": "integer" } }, "conditions": { "type": "object", "description": "A combination of parameters configured during rule creation.", "properties": { "hash": { "type": "string", "description": "SHA256 hash" }, "path": { "type": "string", "description": "Path to the required files or folders" }, "signer": { "type": "string", "description": "Trusted signer" }, "command": { "type": "string", "description": "Command line argument" }, "sign_thumbprint": { "type": "string", "description": "Certificate thumbprint" } } }, "profile_ids": { "type": "array", "description": "A list of profile ids to which the rule is applied.", "nullable": true, "items": { "type": "integer" } }, "status": { "type": "string", "description": "Status of the rule (for example, `enabled` or `disabled`)." }, "scope": { "type": "string", "description": "Specifies the scope of the rule, such as `global` (All endpoints) or `profile` (Exception profiles)." } } }, "DisablePreventionDeleteRulesPAPIRequest": { "type": "object", "required": [ "rule_ids" ], "properties": { "rule_ids": { "type": "array", "minLength": 1, "description": "The unique identifier of the Disable Prevention rule.", "items": { "type": "string", "example": "00e2308ad4a54fca8b478766ee9de57e" } } } }, "GetDistributionDataRequest": { "title": "GetDistributionDataRequest", "type": "object", "description": "Request body containing pagination, sorting, and filtering parameters.", "properties": { "search_from": { "type": "integer", "description": "Starting index for pagination (zero-based). Defines the offset from which to begin returning results.", "minimum": 0, "example": 0, "default": 0 }, "search_to": { "type": "integer", "description": "Ending index for pagination (exclusive). Defines the maximum number of results to return (`search_to` - `search_from`). The maximum allowed value is <=100. Requests exceeding this limit will return a 400 error.", "example": 10, "minimum": 1, "maximum": 100, "default": 100 }, "sort": { "type": "object", "required": [ "field", "keyword" ], "properties": { "field": { "type": "string", "description": "The field name to filter on. Available fields include:\n- `distribution_id`\n- `name`\n- `description`\n- `package_type`\n- `platform`\n- `agent_version`\n- `status`" }, "keyword": { "description": "Determines the sort order.", "enum": [ "asc", "desc" ], "example": "desc" } } }, "filters": { "type": "array", "description": "Filter condition to apply to the query", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "The field name to filter on. Available fields include:\n- `distribution_id`\n- `name`\n- `description`\n- `package_type`\n- `platform`\n- `agent_version`\n- `status`\n", "example": "platform", "minLength": 1 }, "operator": { "description": "Comparison operator to use for filtering.\n**Note:** The `package_type`, `platform`, and `status` fields are **enum** types and therefore do not support the `contains` or `not_contains` filter operators.\n", "enum": [ "eq", "neq", "contains", "not_contains" ], "example": "eq" }, "value": { "oneOf": [ { "type": "string", "example": "lin" }, { "type": "integer" } ], "description": "The value to compare against. Type should match the field type.\nCan be a string or number depending on the operator.\n**Examples:**\n* If the `field` is `status`, the `value` can be `completed`, `in_progress`, or `failed`\n* If the `field` is `platform`, the `value` can be a string such as `windows`, `macos`, `ios`, `serverless`, or `linux`\n* If the `field` is `package_type`, the `value` can be `standalone`, `kubernetes`, `upgrade`, or `helm` " } } } } } }, "GetDistributionDataResponse": { "type": "object", "description": "Response object containing the list of distributions and metadata", "required": [ "reply" ], "properties": { "reply": { "type": "object", "description": "Container object for the response data", "properties": { "data": { "type": "array", "description": "Array of distribution objects matching the filter criteria", "items": { "$ref": "#/components/schemas/Distribution" } }, "filter_count": { "type": "integer", "description": "Number of distributions returned in the current response after applying filters.", "example": 1 }, "total_count": { "type": "integer", "description": "Total number of distributions available in the system without filters.", "example": 10 } } } }, "x-examples": { "Example 1": { "reply": { "data": [ { "distribution_id": "068bcaad02974ac5b223bfa786e7573c", "name": "macos-369121", "description": "Production-ready macos agent installer with enhanced monitoring capabilities", "package_type": "standalone", "platform": "macos", "agent_version": "9.1.0.9877", "status": "completed", "tags": [ "production", "stable" ], "eol_time": 1735689600, "created_by": "John Doe", "creation_time": 1704067200, "modification_time": 1704153600, "supported_packages": [ "pkg" ] } ], "filter_count": 1, "total_count": 10 } } } }, "Distribution": { "type": "object", "description": "Represents an agent distribution package/installer", "properties": { "distribution_id": { "type": "string", "description": "Unique identifier for the distribution", "example": "068bcaad02974ac5b223bfa786e7573c" }, "name": { "type": "string", "description": "Human-readable name of the distribution", "example": "macos-369121" }, "description": { "type": "string", "description": "Detailed description of the distribution, its features, or release notes", "example": "Production-ready macos agent installer with enhanced monitoring capabilities", "nullable": true }, "package_type": { "type": "string", "description": "Type of installation package", "example": "standalone" }, "platform": { "type": "string", "description": "Target operating system or platform", "example": "macos" }, "agent_version": { "type": "string", "description": "Version number of the agent in semantic versioning format", "example": "9.1.0.9877" }, "status": { "type": "string", "description": "Current lifecycle status of the distribution.", "example": "completed" }, "tags": { "type": "array", "description": "Array of tags for categorization and filtering", "example": [ "production", "stable" ], "items": { "type": "string" } }, "eol_time": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds (UTC) indicating the date and time when the resource reaches End-of-Life (EOL).", "example": 1735689600, "nullable": true }, "created_by": { "type": "string", "description": "Name of the user or API key ID that created the distribution.", "example": "John Doe" }, "creation_time": { "type": "integer", "description": "Unix timestamp (milliseconds) when the distribution was created.", "example": 1704067200 }, "modification_time": { "type": "integer", "description": "Unix timestamp (milliseconds) when the distribution was modified.", "example": 1704153600 }, "supported_packages": { "type": "array", "description": "List of package formats supported by this distribution", "example": [ "pkg" ], "items": { "type": "string" } } } } } }, "paths": { "/public_api/v1/xql/start_xql_query": { "post": { "tags": [ "XQL Query" ], "summary": "Start an XQL Query", "operationId": "postStartXqlQuery", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "description": "Execute an XQL query.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex XDR allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "example": { "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [], "timeframe": { "from": "1598907600000", "to": "1599080399000" } } }, "type": "object", "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "String of the XQL query." }, "tenants": { "type": "array", "description": "Note: This is only used when querying tenants managed by Managed Security Services Providers (MSSP).\r\n\r\nList of strings used for running APIs on local and Managed Security tenants. Valid values:\r\n- For single tenant (local tenant) query, enter a single-item list with your tenant_id. Additional valid values are, empty list ([]) or null (default).\r\n- For multi-tenant investigations (Managed Security parent who investigate children and/or local), enter multi-item list with the required tenant_id. List of IDs can contain the parent, children, or both parent and children.", "items": { "type": "string" } }, "timeframe": { "type": "object", "description": "Integer in timestamp epoch milliseconds.\r\nValid values include:\r\n- Absolute Unix timestamp representing a date period: {\"from\" : 1598907600000, \"to\" : 1599080399000} = date period: 31/08/20 09:00:00 PM UTC - 02/09/20 8:59:59 PM UTC\r\n- Relative Unix timestamp representing the last 24 hours: {\"relativeTime\": 86400000} = (24 * 60 * 60 * 1000 = 86400000).", "properties": { "from": { "type": "integer", "description": "Use for an absolute timeframe in Unix timestamp." }, "to": { "type": "integer", "description": "Use for an absolute timeframe in Unix timestamp." }, "relativeTime": { "type": "string", "description": "Use for a relative Unix timestamp." } } } } } } }, "examples": { "example-1": { "value": { "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [ "431509831", "401387390" ], "timeframe": { "from": 1598907600000, "to": 1599080399000 } } } } } } }, "description": "" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" } }, "x-examples": { "Example 1": { "reply": "ad21c1e1492d4c_667_inv" } } }, "examples": { "Example 1": { "value": { "reply": "ad21c1e1492d4c_667_inv" } } } } } }, "400": { "description": "Bad Request. Invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } } } } }, "/public_api/v1/xql/get_query_results": { "post": { "operationId": "postGetQueryResults", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "XQL Query" ], "summary": "Get XQL Query Results", "description": "Retrieve results of an executed XQL query API.\n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nMaximum result set size is 1000. The API does not support pagination, therefore, you can set values to determine the result size limitation and how to wait for the results. To view response with greater than 1000 results you must call [Get XQL Query Results Stream](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/xql-query#post-public_api-v1-xql-get_query_results_stream).\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex XDR allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "query_id": "061880b4867446_4356_inv", "pending_flag": true, "limit": 100, "format": "json" } }, "properties": { "request_data": { "type": "object", "required": [ "query_id" ], "properties": { "query_id": { "type": "string", "description": "String representing the unique execution ID generated by the response to [Start an XQL Query](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/xql-query#post-public_api-v1-xql-start_xql_query) API.\r\nYou can also enter the execution ID of a query generated in Cortex XDR and listed in the Query Center table." }, "pending_flag": { "type": "boolean", "description": "Boolean flag indicating whether the API call should operate in synchronous/blocking mode, or in asynchronous/non-blocking mode. Valid Values:\r\n- True (default): The call returns immediately with one of the following options:\r\n1) PENDING status indicating query hasn't yet completed or results are not yet ready to be returned. Need to execute the API call again.\r\n2) SUCCESS/FAIL status\r\n- False: The API will block until query completes and results are ready to be returned." }, "limit": { "type": "integer", "description": "Integer representing the maximum number of results to return.\r\nIf the 'limit' is not specified or if 'limit' is greater than 1000 and the query yields more than 1000 valid results, a `stream id` will be generated for use in the *Get XQL Query Results Stream** API.\r\nIn the context of multi-tenant investigations, when you specify the parameter value (x),\r\nit will return x results across all tenants combined, rather than x results for each individual tenant.\r\nFor example, if there are y tenants participating in the investigation, the maximum number of results returned can be x*y (up to the limit of 1,000,000)." }, "format": { "enum": [ "json", "csv" ], "description": "The type of response output." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "query_id": "061880b4867446_4356_inv", "pending_flag": true, "limit": 100, "format": "json" } } } } } }, "description": "" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "status": { "type": "string" }, "number_of_results": { "type": "integer" }, "query_cost": { "type": "object", "properties": { "9995067425505": { "type": "number" } } }, "remaining_quota": { "type": "number" }, "results": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "agent_version": { "type": "string" }, "_product": { "type": "string" }, "_time": { "type": "integer" }, "_vendor": { "type": "string" }, "insert_timestamp": { "type": "integer" }, "agent_os_type": { "type": "string" }, "event_type": { "type": "string" }, "event_sub_type": { "type": "string" } } } } } } } } }, "x-examples": { "Example 1": { "reply": { "status": "SUCCESS", "number_of_results": 1, "query_cost": { "9995067425505": 0.01298138888888889 }, "remaining_quota": 4.969819444444444, "results": { "data": [ { "event_id": "MTQ5MDE0OTI5NjE2NDY2NTI3NA==", "agent_version": "7.7.0.60725", "_product": "Fusion", "_time": 1690877704746, "_vendor": "PANW", "insert_timestamp": 1690877878272, "agent_os_type": "AGENT_OS_WINDOWS", "event_type": "STORY", "event_sub_type": "event_sub_type_4" } ] } } } } }, "examples": { "pending_flag=true": { "value": { "reply": { "status": "PENDING" } } }, "Up to 1,000 results, JSON format, Single Tenant Investigation": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 3, "query_cost": { "tenant_id_1": 0.001596388888888889 }, "remaining_quota": 4.998403611111111, "results": { "data": [ { "event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL" } ] } } } }, "Up to 1,000 results, CSV format, Single Tenant Investigation": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 3, "query_cost": { "tenant_id_1": 0.001596388888888889 }, "remaining_quota": 4.998403611111111, "results": { "data": "_vendor,_product,insert_timestamp,event_id1,_time,event_type,event_sub_type\r\nPANW,Fusion,2021-05-20 20:17:05.324000+00:00,eventID,2021-05-20 20:12:03+00:00,STORY,NULL\r\nPANW,Fusion,2021-05-20 20:17:05.326000+00:00,eventID2,2021-05-20 20:12:08+00:00,STORY,NULL\r\nPANW,Fusion,2021-05-20 20:17:05.325000+00:00,eventID3,2021-05-20 20:11:57+00:00,STORY,NULL\r\n" } } } }, "Up to 1,000 results, JSON format, Multi Tenant Investigation": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 6, "query_cost": { "tenant_id_1": 0.001596388888888889, "tenant_id_2": 0.00179989 }, "remaining_quota": 4.995007332222222, "results": { "data": [ { "event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID4", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" }, { "event_id": "eventID5", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" }, { "event_id": "eventID6", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" } ] } } } }, "More than 1,000 results": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 1000000, "query_cost": { "tenant_id_1": 0.011742777777777777 }, "remaining_quota": 4.984442777777778, "results": { "stream_id": "streamID" } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/xql/get_quota": { "post": { "operationId": "postGetQuota", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "XQL Query" ], "summary": "Get XQL Query Quota", "description": "Retrieve the amount of query quota available and used for this tenant, including the number of daily running queries, the number of active queries, and the number of queries run concurrently today on this tenant.\n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex XDR allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": {} } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "license_quota": 5, "additional_purchased_quota": 0, "used_quota": 0.07041027777777777, "eval_quota": 0 } } }, "properties": { "reply": { "type": "object", "properties": { "license_quota": { "type": "integer" }, "additional_purchased_quota": { "type": "integer" }, "used_quota": { "type": "number" }, "eval_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries. This value is reset nightly." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API. This value is reset nightly." }, "current_concurrent_active_queries": { "type": "object", "description": "Currently running XQL queries with their current duration.", "additionalProperties": { "type": "string" } }, "current_concurrent_active_queries_count": { "type": "integer", "description": "The number of active queries currently running." }, "max_daily_concurrent_active_query_count": { "type": "integer", "description": "The maximum number of queries that ran concurrently today on this tenant. This value is reset nightly." } } } } }, "examples": { "example-1": { "value": { "reply": { "license_quota": 5, "additional_purchased_quota": 0, "used_quota": 0, "eval_quota": 0, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 8, "current_concurrent_active_queries": { "debee6b0c41f47_911_inv": { "xql": "config timeframe = 1mo | dataset=xdr_data | limit 1000000", "duration": 61 } }, "current_concurrent_active_queries_count": 1, "max_daily_concurrent_active_query_count": 4 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer" }, "total_daily_concurrent_rejected_queries": { "type": "integer" } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/xql/get_query_results_stream": { "post": { "operationId": "postGetQueryResultsStream", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" }, { "schema": { "type": "string" }, "in": "header", "name": "'Accept-Encoding: gzip' : \" \"", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "XQL Query" ], "summary": "Get XQL Query Results Stream", "description": "Retrieve XQL query results with more than 1000 results.\n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nResponse is returned as chunked (Transfer-Encoding: chunked). To retrieve a compressed gzipped response (Content-Encoding: gzip), in your header add Accept-Encoding: gzip.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex XDR allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "stream_id": "563c5e24-===-9a1f8139d3c5", "is_gzip_compressed": true } }, "properties": { "request_data": { "type": "object", "required": [ "stream_id" ], "properties": { "stream_id": { "type": "string", "description": "String representing the unique ID generate by the response to [Get XQL Query Results](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/xql-query#post-public_api-v1-xql-get_query_results) API." }, "is_gzip_compressed": { "type": "boolean", "description": "A boolean flag indicating whether the response should be compressed and gzipped." } } } }, "required": [ "request_data" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "examples": {} } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/incidents/get_incidents": { "post": { "operationId": "postGetIncidents", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Get all Incidents", "description": "Get a list of incidents filtered by a list of incident IDs, modification time, or creation time. This includes all incident types and severities, including correlation-generated incidents.\n- The response is concatenated using AND condition (OR is not supported).\n- The maximum result set size is >100.\n- Offset is the zero-based number of incidents from the start of the result set.\n\nNote: You can send a request to retrieve either **all** or **filtered** results.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "filters": [ { "field": "incident_id_list", "operator": "in", "value": [ "", "" ] } ], "search_from": 0, "search_to": 100, "sort": { "field": "creation_time", "keyword": "desc" } } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.\nAn empty dictionary returns all results.", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "type": "string", "description": "Identifies the incident field the filter is matching. Filters are based on the following keywords:\n- `modification_time`: Time the incident has been modified.\n- `creation_time`: Incident's creation time.\n- `incident_id`: Incident ID.\n- `incident_id_list`: List of incident IDs.\n- `description`: Incident description.\n- `alert_sources`: Source that detected the alert.\n- `status`: The status of the incident.\n- `starred`: Whether the incident is starred.", "enum": [ "modification_time", "creation_time", "incident_id_list", "description", "alert_sources", "status", "incident_id", "starred" ] }, "operator": { "type": "string", "description": "Identifies the comparison operator you want to use for this filter. Valid keywords are:\n`in`: \n- `incident_id_list`, `alert_sources`, `description`: List of Strings\n`contains`\n- `description`: String\n`gte` / `lte`\n- `modification_time`, `creation_time`: Integer in timestamp epoch milliseconds\n`eq` / `neq`\n- `status`: String\n- `starred`: Boolean\n", "enum": [ "in", "contains", "gte", "lte", "eq", "neq" ] }, "value": { "type": [ "array", "integer", "string", "boolean" ], "description": "Value that this filter must match. The contents of this field will differ depending on the incident field that you specified for this filter:\n- `modification_time`, `creation_time`: Integer representing the number of milliseconds after the Unix epoch, UTC timezone.\n- `description`: List of strings.\n- `incident_id`: String.\n- `incident_id_list`: List of strings. Each item in the list muste be an incident ID.\n- `alert_sources`: List of strings.\n- `status`: Single value, can be one of the following: `resolved_duplicate`, `resolved_other`, `new`, `resolved_security_testing`, `resolved_known_issue`, `resolved_auto`, `resolved_threat_handled`, `resolved_true_positive`, `under_investigation`, or `resolved_false_positive`.\n- `starred`: Boolean value: `true` or `false`.", "items": {} } } } }, "search_from": { "type": "integer", "description": "Integer representing the starting offset within the query result set from which you want incidents returned.\nIncidents are returned as a zero-based list. Any incident indexed less than this value is not returned in the final result set and defaults to zero." }, "search_to": { "type": "integer", "description": "Integer representing the end offset within the result set after which you do not want incidents returned.\nIncidents in the incident list that are indexed higher than this value are not returned in the final results set. Defaults to >100, which returns all incidents to the end of the list." }, "sort": { "type": "object", "description": "Identifies the sort order for the result set.", "required": [ "field", "keyword" ], "properties": { "field": { "description": "Sort according to this field. Valid options are: \r\n- `creation_time`\r\n- `incident_id`\r\n- `modification_time`", "enum": [ "creation_time", "incident_id", "modification_time" ] }, "keyword": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort in ascending or descending order." } } } } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "incident_id_list", "operator": "in", "value": [ "", "" ] } ], "search_from": 0, "search_to": 100, "sort": { "field": "creation_time", "keyword": "desc" } } } } } } }, "description": "If no parameters are included, all results will be returned." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "total_count": 1, "result_count": 1, "incidents": [ { "incident_id": "", "incident_name": "test", "creation_time": 1577024425126, "modification_time": 1577024425126, "detection_time": null, "status": "resolved_known_issue", "severity": "medium", "description": "Memory Corruption Exploit generated by XDR Agent", "assigned_user_mail": null, "assigned_user_pretty_name": null, "alert_count": 1, "low_severity_alert_count": 0, "med_severity_alert_count": 1, "high_severity_alert_count": 0, "critical_severity_alert_count": 0, "user_count": 1, "host_count": 1, "notes": null, "resolve_comment": null, "resolved_timestamp": 1577024425126, "manual_severity": null, "manual_description": "Memory Corruption Exploit generated by XDR Agent", "xdr_url": "https://", "starred": false, "hosts": [ "" ], "users": [ "test_1", "test_2" ], "incident_sources": [ "XDR Agent", "XDR BIOC" ], "rule_based_score": 342, "manual_score": null, "wildfire_hits": 0, "alerts_grouping_status": "Enabled", "mitre_tactics_ids_and_names": [ "TA0004 - Privilege Escalation", "TA0005 - Defense Evasion", "TA0006 - Credential Access" ], "mitre_techniques_ids_and_names": [ "T1001.001 - Data Obfuscation: Junk Data", "T1001.002 - Data Obfuscation: Steganography", "T1001.003 - Data Obfuscation: Protocol Impersonation" ], "alert_categories": [ "Credential Access", "Exploit", "Spyware Detected via Anti-Spyware profile" ], "original_tags": [ "DS:PANW/NGFW", "EG:acme-2", "EG:Acme group", "DS:PANW/XDR Agent" ], "tags": [ "EG:Acme group", "DS:PANW/NGFW", "DS:PANW/XDR Agent", "EG:acme-2" ] } ], "restricted_incident_ids": [] } } }, "properties": { "reply": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "The total number of possible results.", "maximum": 10000 }, "result_count": { "type": "integer", "description": "The number of incidents actually returned as result." }, "incidents": { "type": "array", "description": "A list of incidents.\n\nNote: If a manual_description was set, the description field will display the manual description and the system description is not returned.\n\nDepending on the defined user permissions, with full permissions, the response displays original_tags and tags fields.", "items": { "type": "object", "properties": { "incident_id": { "type": "string" }, "incident_name": { "type": "string" }, "creation_time": { "type": "integer" }, "modification_time": { "type": "integer" }, "detection_time": { "nullable": true }, "status": { "type": "string" }, "severity": { "type": "string" }, "description": { "type": "string" }, "assigned_user_mail": { "nullable": true }, "assigned_user_pretty_name": { "nullable": true }, "alert_count": { "type": "integer" }, "low_severity_alert_count": { "type": "integer" }, "med_severity_alert_count": { "type": "integer" }, "high_severity_alert_count": { "type": "integer" }, "critical_severity_alert_count": { "type": "integer" }, "user_count": { "type": "integer" }, "host_count": { "type": "integer" }, "notes": { "nullable": true }, "resolve_comment": { "nullable": true }, "resolved_timestamp": { "type": "integer" }, "manual_severity": { "nullable": true }, "manual_description": { "type": "string" }, "xdr_url": { "type": "string" }, "starred": { "type": "boolean" }, "starred_manually": { "type": "boolean", "description": "True = this incident was manually starred.\r\nFalse = This incident was starred by starring rules." }, "hosts": { "type": "array", "items": { "type": "string" } }, "users": { "type": "array", "items": { "type": "string" } }, "incident_sources": { "type": "array", "items": { "type": "string" } }, "rule_based_score": { "type": "integer" }, "manual_score": { "nullable": true }, "wildfire_hits": { "type": "integer" }, "alerts_grouping_status": { "type": "string" }, "mitre_tactics_ids_and_names": { "type": "array", "items": { "type": "string" } }, "mitre_techniques_ids_and_names": { "type": "array", "items": { "type": "string" } }, "alert_categories": { "type": "array", "items": { "type": "string" } }, "original_tags": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "restricted_incident_ids": { "type": "array", "description": "Depending on the defined user permissions, in restrictive or partial permission mode, the response displays only the incident ID. For example:\n\n\"restricted_incident_ids\": [ \"1491\"]", "items": { "type": "object" } } } } } }, "examples": { "Success Response Example": { "value": { "reply": { "total_count": 1, "result_count": 1, "incidents": [ { "incident_id": "", "incident_name": "test", "creation_time": 1577024425126, "modification_time": 1577024425126, "detection_time": null, "status": "resolved_known_issue", "severity": "medium", "description": "Memory Corruption Exploit generated by XDR Agent", "assigned_user_mail": null, "assigned_user_pretty_name": null, "alert_count": 1, "low_severity_alert_count": 0, "med_severity_alert_count": 1, "high_severity_alert_count": 0, "critical_severity_alert_count": 0, "user_count": 1, "host_count": 1, "notes": null, "resolve_comment": null, "resolved_timestamp": 1577024425126, "manual_severity": null, "manual_description": "Memory Corruption Exploit generated by XDR Agent", "xdr_url": "https://", "starred": false, "hosts": [ "" ], "users": [ "test_1", "test_2" ], "incident_sources": [ "XDR Agent", "XDR BIOC" ], "rule_based_score": 342, "manual_score": null, "wildfire_hits": 0, "alerts_grouping_status": "Enabled", "mitre_tactics_ids_and_names": [ "TA0004 - Privilege Escalation", "TA0005 - Defense Evasion", "TA0006 - Credential Access" ], "mitre_techniques_ids_and_names": [ "T1001.001 - Data Obfuscation: Junk Data", "T1001.002 - Data Obfuscation: Steganography", "T1001.003 - Data Obfuscation: Protocol Impersonation" ], "alert_categories": [ "Credential Access", "Exploit", "Spyware Detected via Anti-Spyware profile" ], "original_tags": [ "DS:PANW/NGFW", "EG:acme-2", "EG:Acme group", "DS:PANW/XDR Agent" ], "tags": [ "EG:Acme group", "DS:PANW/NGFW", "DS:PANW/XDR Agent", "EG:acme-2" ], "starred_manually": true } ], "restricted_incident_ids": [] } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/alerts/get_alerts": { "post": { "summary": "Get all Alerts", "tags": [ "Incident Management" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "total_count": 45, "result_count": 1, "alerts": [ { "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_device_domain": null, "agent_fqdn": "test", "agent_os_type": "Windows", "agent_os_sub_type": "", "agent_data_collection_status": true, "mac": null, "mac_address": [ "" ], "agent_is_vdi": null, "contains_featured_host": false, "contains_featured_user": false, "contains_featured_ip": false, "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": "", "actor_process_image_path": "c:\\\\virus.exe", "actor_process_image_name": "virus.exe", "actor_process_command_line": "c:\\\\virus.exe", "actor_process_signature_status": "N/A", "actor_process_signature_vendor": null, "actor_process_image_sha256": "", "actor_process_image_md5": null, "actor_process_causality_id": null, "actor_causality_id": null, "actor_process_os_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": "", "detection_timestamp": 1603279888980, "name": "Kernel Privilege Escalation", "category": "Exploit", "endpoint_id": "", "description": "Local privilege escalation prevented", "host_ip": [ "" ], "host_name": "Test", "source": "XDR Agent", "action": "BLOCKED", "action_pretty": "Prevented (Blocked)", "variation_rule_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ] } } }, "properties": { "reply": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "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": { "type": "integer", "description": "Number of alerts actually returned as result." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "severity": { "type": "string" }, "matching_status": { "type": "string" }, "end_match_attempt_ts": { "type": "integer" }, "local_insert_ts": { "type": "integer" }, "bioc_indicator": { "nullable": true }, "matching_service_rule_id": { "nullable": true }, "attempt_counter": { "type": "integer" }, "bioc_category_enum_key": { "nullable": true }, "is_whitelisted": { "type": "boolean" }, "starred": { "type": "boolean" }, "deduplicate_tokens": { "nullable": true }, "filter_rule_id": { "nullable": true }, "mitre_technique_id_and_name": { "type": "array", "items": { "type": "string" } }, "mitre_tactic_id_and_name": { "type": "array", "items": { "type": "string" } }, "agent_version": { "type": "string" }, "agent_device_domain": { "nullable": true }, "agent_fqdn": { "type": "string" }, "agent_os_type": { "type": "string" }, "agent_os_sub_type": { "type": "string" }, "agent_data_collection_status": { "type": "boolean" }, "mac": { "nullable": true }, "mac_address": { "type": "array", "items": { "type": "string" } }, "agent_is_vdi": { "nullable": true }, "contains_featured_host": { "type": "boolean" }, "contains_featured_user": { "type": "boolean" }, "contains_featured_ip": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "object", "properties": { "agent_install_type": { "type": "string" }, "agent_host_boot_time": { "nullable": true }, "event_sub_type": { "nullable": true }, "module_id": { "type": "string" }, "association_strength": { "nullable": true }, "dst_association_strength": { "nullable": true }, "story_id": { "nullable": true }, "event_id": { "nullable": true }, "event_type": { "type": "string" }, "event_timestamp": { "type": "integer" }, "actor_process_instance_id": { "type": "string" }, "actor_process_image_path": { "type": "string" }, "actor_process_image_name": { "type": "string" }, "actor_process_command_line": { "type": "string" }, "actor_process_signature_status": { "type": "string" }, "actor_process_signature_vendor": { "nullable": true }, "actor_process_image_sha256": { "type": "string" }, "actor_process_image_md5": { "nullable": true }, "actor_process_causality_id": { "nullable": true }, "actor_causality_id": { "nullable": true }, "actor_process_os_pid": { "type": "string" }, "actor_thread_thread_id": { "nullable": true }, "causality_actor_process_image_name": { "nullable": true }, "causality_actor_process_command_line": { "nullable": true }, "causality_actor_process_image_path": { "nullable": true }, "causality_actor_process_signature_vendor": { "nullable": true }, "causality_actor_process_signature_status": { "type": "string" }, "causality_actor_causality_id": { "nullable": true }, "causality_actor_process_execution_time": { "nullable": true }, "causality_actor_process_image_md5": { "nullable": true }, "causality_actor_process_image_sha256": { "nullable": true }, "action_file_path": { "nullable": true }, "action_file_name": { "nullable": true }, "action_file_md5": { "nullable": true }, "action_file_sha256": { "nullable": true }, "action_file_macro_sha256": { "nullable": true }, "action_registry_data": { "nullable": true }, "action_registry_key_name": { "nullable": true }, "action_registry_value_name": { "nullable": true }, "action_registry_full_key": { "nullable": true }, "action_local_ip": { "nullable": true }, "action_local_port": { "nullable": true }, "action_remote_ip": { "nullable": true }, "action_remote_port": { "nullable": true }, "action_external_hostname": { "nullable": true }, "action_country": { "type": "string" }, "action_process_instance_id": { "nullable": true }, "action_process_causality_id": { "nullable": true }, "action_process_image_name": { "nullable": true }, "action_process_image_sha256": { "nullable": true }, "action_process_image_command_line": { "nullable": true }, "action_process_signature_status": { "type": "string" }, "action_process_signature_vendor": { "nullable": true }, "os_actor_effective_username": { "nullable": true }, "os_actor_process_instance_id": { "nullable": true }, "os_actor_process_image_path": { "nullable": true }, "os_actor_process_image_name": { "nullable": true }, "os_actor_process_command_line": { "nullable": true }, "os_actor_process_signature_status": { "type": "string" }, "os_actor_process_signature_vendor": { "nullable": true }, "os_actor_process_image_sha256": { "nullable": true }, "os_actor_process_causality_id": { "nullable": true }, "os_actor_causality_id": { "nullable": true }, "os_actor_process_os_pid": { "nullable": true }, "os_actor_thread_thread_id": { "nullable": true }, "fw_app_id": { "nullable": true }, "fw_interface_from": { "nullable": true }, "fw_interface_to": { "nullable": true }, "fw_rule": { "nullable": true }, "fw_rule_id": { "nullable": true }, "fw_device_name": { "nullable": true }, "fw_serial_number": { "nullable": true }, "fw_url_domain": { "nullable": true }, "fw_email_subject": { "nullable": true }, "fw_email_sender": { "nullable": true }, "fw_email_recipient": { "nullable": true }, "fw_app_subcategory": { "nullable": true }, "fw_app_category": { "nullable": true }, "fw_app_technology": { "nullable": true }, "fw_vsys": { "nullable": true }, "fw_xff": { "nullable": true }, "fw_misc": { "nullable": true }, "fw_is_phishing": { "type": "string" }, "dst_agent_id": { "nullable": true }, "dst_causality_actor_process_execution_time": { "nullable": true }, "dns_query_name": { "nullable": true }, "dst_action_external_hostname": { "nullable": true }, "dst_action_country": { "nullable": true }, "dst_action_external_port": { "nullable": true }, "user_name": { "nullable": true } } } }, "alert_id": { "type": "string" }, "detection_timestamp": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string" }, "endpoint_id": { "type": "string" }, "description": { "type": "string" }, "host_ip": { "type": "array", "items": { "type": "string" } }, "host_name": { "type": "string" }, "source": { "type": "string" }, "action": { "type": "string" }, "action_pretty": { "type": "string" }, "variation_rule_id": { "type": "string" } } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "total_count": 20834, "result_count": 1, "alerts": [ { "agent_os_sub_type": "6.3.9600", "fw_app_category": null, "fw_app_id": null, "fw_app_subcategory": null, "fw_app_technology": null, "causality_actor_process_command_line": null, "causality_actor_process_image_md5": null, "causality_actor_process_image_name": null, "causality_actor_process_image_path": null, "causality_actor_process_image_sha256": null, "causality_actor_process_signature_status": "N/A", "causality_actor_process_signature_vendor": null, "causality_actor_causality_id": null, "identity_sub_type": null, "identity_type": null, "operation_name": null, "project": null, "cloud_provider": null, "referenced_resource": null, "resource_sub_type": null, "resource_type": null, "cluster_name": null, "container_id": null, "contains_featured_host": "NO", "contains_featured_ip": "NO", "contains_featured_user": "NO", "action_country": "UNKNOWN", "fw_interface_to": null, "dns_query_name": null, "agent_device_domain": "attractions.disney.com", "fw_email_recipient": null, "fw_email_sender": null, "fw_email_subject": null, "event_type": null, "is_whitelisted": false, "action_file_macro_sha256": null, "action_file_md5": null, "action_file_name": null, "action_file_path": null, "action_file_sha256": null, "fw_device_name": null, "fw_rule_id": null, "fw_rule": null, "fw_serial_number": null, "agent_fqdn": "FL-ATR-DC3-04.attractions.disney.com", "mac": "00:50:56:bb:34:34,00:50:56:bc:bc:2f", "agent_os_type": "Windows", "image_name": null, "actor_process_image_name": "10.91.72.115", "actor_process_command_line": null, "actor_process_image_md5": null, "actor_process_image_path": null, "actor_process_os_pid": null, "actor_process_image_sha256": null, "actor_process_signature_status": "N/A", "actor_process_signature_vendor": null, "actor_thread_thread_id": null, "fw_is_phishing": "N/A", "action_local_ip": null, "action_local_port": null, "fw_misc": null, "mitre_tactic_id_and_name": "TA0007 - Discovery", "mitre_technique_id_and_name": "T1012 - Query Registry", "module_id": "Behavioral Threat Protection", "fw_vsys": null, "os_actor_process_command_line": null, "os_actor_thread_thread_id": null, "os_actor_process_image_name": null, "os_actor_process_os_pid": null, "os_actor_process_image_sha256": null, "os_actor_process_signature_status": "N/A", "os_actor_process_signature_vendor": null, "os_actor_effective_username": null, "action_process_signature_status": "N/A", "action_process_signature_vendor": null, "action_registry_data": null, "action_registry_full_key": null, "action_external_hostname": null, "action_remote_ip": "10.71.62.215", "action_remote_port": null, "matching_service_rule_id": null, "fw_interface_from": null, "starred": false, "action_process_image_command_line": null, "action_process_image_name": null, "action_process_image_sha256": null, "fw_url_domain": null, "user_agent": null, "fw_xff": null, "alert_domain": "DOMAIN_SECURITY", "external_id": "7c96737d50f74c7b9487450426e9eafb", "severity": "high", "matching_status": "MATCHED", "end_match_attempt_ts": null, "local_insert_ts": 1706539597503, "last_modified_ts": 1706539706370, "bioc_indicator": null, "attempt_counter": 0, "bioc_category_enum_key": null, "case_id": 391722, "deduplicate_tokens": null, "filter_rule_id": null, "agent_version": "8.1.0.42616", "agent_ip_addresses_v6": null, "agent_data_collection_status": false, "agent_is_vdi": false, "agent_install_type": "STANDARD", "agent_host_boot_time": null, "event_sub_type": null, "association_strength": 50, "dst_association_strength": null, "story_id": null, "event_id": null, "event_timestamp": 1706540499609, "actor_process_instance_id": null, "actor_process_causality_id": null, "actor_causality_id": null, "causality_actor_process_execution_time": null, "action_registry_key_name": null, "action_registry_value_name": null, "action_local_ip_v6": null, "action_remote_ip_v6": null, "action_process_instance_id": null, "action_process_causality_id": null, "os_actor_process_instance_id": null, "os_actor_process_image_path": null, "os_actor_process_causality_id": null, "os_actor_causality_id": null, "dst_agent_id": null, "dst_causality_actor_process_execution_time": null, "dst_action_external_hostname": null, "dst_action_country": null, "dst_action_external_port": null, "is_pcap": false, "image_id": null, "container_name": null, "namespace": null, "alert_type": "Unclassified", "resolution_status": "STATUS_020_UNDER_INVESTIGATION", "resolution_comment": null, "dynamic_fields": null, "tags": "DS:PANW/XDR Agent", "malicious_urls": null, "dss_job_title": null, "dss_department": null, "dss_country": null, "dss_groups": null, "alert_id": "50023290705", "detection_timestamp": 1706540499609, "name": "Behavioral Threat", "category": "Malware", "endpoint_id": "866d9341c27a4df389b246d977d216ec", "description": "Behavioral threat detected (rule: sync.query_ntdsdit_vssadmin_remote)", "host_ip": "10.71.62.2,10.71.62.5", "host_name": "hostname", "source": "XDR Agent", "action": "REPORTED", "action_pretty": "Detected (Reported)", "user_name": null, "events_length": 1, "original_tags": "DS:PANW/XDR Agent" } ] } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON." }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters." }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API." }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API." }, "500": { "description": "Internal server error. A unified status for API communication type errors." } }, "operationId": "post-public_api-v1-alerts-get_alerts", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "description": "Get a list of all or filtered alerts. The alerts listed are what remains after alert exclusions are applied by Cortex XDR.\r\n\r\n- Response is concatenated using AND condition (OR is not supported).\r\n- Maximum result set size is 100.\r\n- Offset is the zero-based number of alerts from the start of the result set.\r\nThe response indicates whether an PAN NGFW type alert contains a PCAP triggering packet. Use the Retrieve PCAP Packet API to retrieve a list of alert IDs and their associated PCAP data.\r\n\r\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "description": "If no parameters are included, all results will be returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "enum": [ "alert_id_list", "alert_source", "severity", "creation_time", "server_creation_time" ], "description": "Identifies the alert field the filter is matching. Filters are based on the following keywords:\r\n- `alert_id_list`: List of integers representing the alert IDs.\r\n- `alert_source`: List of strings representing the alert sources.\r\n- `severity`: List of strings representing the alert severities.\r\n- `creation_time`: Timestamp of when the alert was originally identified.\r\n- `server_creation_time`: Timestamp of when the alert was stored in the database." }, "operator": { "enum": [ "in", "gte", "lte" ], "description": "Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`in`: \r\n- `alert_id_list`, `alert_source`, and `severity`\r\n`gte` / `lte`\r\n- `creation_time` and `server_creation_time`" }, "value": { "type": [ "string", "array", "integer" ], "description": "Value that this filter must match. The contents of this field will differ depending on the alert field that you specified for this filter:\r\n- `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.\r\n- `server_creation_time`: Integer representing the number of seconds or milliseconds after the Unix epoch, UTC timezone. The value is represented in XQL as `local_insert_ts`.\r\n- `alert_id_list`: Array of integers. Each item in the list must be an alert ID.\r\n- `severity`: Valid values are `low`, `medium`, `high`, `critical`.", "items": {} } } } }, "search_from": { "type": "integer", "description": "An integer representing the starting offset within the query result set from which you want alerts returned.\r\nAlerts 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": { "type": "integer", "description": "An integer representing the end offset within the result set after which you do not want alerts returned.\r\nAlerts 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": { "type": "object", "description": "Identifies the sort order for the result set. By default the sort is defined as *creation_time*, *desc*.", "required": [ "keyword" ], "properties": { "field": { "type": "string", "description": "Identifies how to sort the result set, either according to severity or creation time. " }, "keyword": { "type": "string", "description": "Defines whether to sort the results in ascending (asc) or descending (desc) order." } } } } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ], "search_from": 0, "search_to": 5, "sort": { "field": "severity", "keyword": "asc" } } } } } } } } } }, "/public_api/v1/incidents/update_incident": { "post": { "operationId": "postUpdateIncident", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Update an Incident", "description": "Update one or more fields of a specific incident. Missing fields are ignored.\nNote the following:\n- `assigned_user_mail` field is validated by Cortex XDR to confirm the provided assignee email address belongs to a user that exists in the same Cortex XDR tenant.\n- To unassign an incident pass `none` or `”assigned_user_mail”: “”`.\n- To remove a manually set severity pass `none` or `“manual_severity”: “”`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": "{ \n \"request_data\":{ \n \"incident_id\":\"\",\n \"update_data\":{ \n \"assigned_user_mail\":\"username@test.com\",\n \"manual_severity\":\"low\",\n \"status\":\"resolved_other\",\n \"resolve_comment\":\"This incident is resolved\"\n }\n }", "properties": { "request_data": { "type": "object", "required": [ "incident_id", "update_data" ], "properties": { "incident_id": { "type": "string", "description": "A string representing the incident ID you want to update." }, "update_data": { "type": "object", "description": "The data to update the incident with.", "properties": { "assigned_user_mail": { "type": "string", "description": "Updated email address of the incident assignee." }, "manual_severity": { "type": "string", "description": "Administrator-defined severity.Updated incident status." }, "status": { "type": "string", "description": "Updated incident status." }, "resolve_comment": { "type": "string", "description": "Descriptive comment explaining the incident change. This can be set only for resolved incidents." }, "comment": { "type": "object", "description": "Add a comment to the incident.", "required": [ "comment_action", "value" ], "properties": { "comment_action": { "type": "string", "description": "The comment action must be 'add'." }, "value": { "type": "string", "description": "The comment text." } } }, "": { "type": "string", "description": "You can include custom incident fields in the request. The names of the custom fields are standardized into lowercase with no white spaces. \r\nor example, `Single Select` would be included as `singleselect`." }, "notes": { "type": "string", "description": "Notes for the incident. If there are already notes, these notes will replace existing notes." } } } } } } }, "examples": { "Request example": { "value": { "request_data": { "incident_id": "2927", "update_data": { "assigned_user_mail": "username@test.com", "manual_severity": "low", "status": "resolved_other", "resolve_comment": "This incident is resolved" } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "Whether the incident update was successful." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors. For example, test@test.com is not a valid Cortex XDR email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/alerts/update_alerts": { "post": { "operationId": "postUpdateAlerts", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Update Alerts", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "alert_id_list": [ "104173821", "574203823", "395720183" ], "update_data": { "severity": "medium", "status": "resolved_other", "comment": "This incident is resolved" } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "alert_id_list", "update_data" ], "properties": { "alert_id_list": { "type": "array", "description": "A list representing the alert IDs you want to update.", "items": { "type": "string" } }, "update_data": { "type": "object", "description": "The data you want to update the alerts with.", "properties": { "severity": { "description": "Alert severity.", "enum": [ "critical", "high", "medium", "low", "informational" ] }, "status": { "description": "Updated alert status.", "enum": [ "new", "under_investigation", "resolved_security_testing", "resolved_known_issue", "resolved_duplicate", "resolved_other", "resolved_false_positive", "resolved_true_positive" ] }, "comment": { "type": "string", "description": "Descriptive comment explaining the changes." } } } } } } }, "examples": { "example-1": { "value": { "request_data": { "alert_id_list": [ "" ], "update_data": { "severity": "low", "status": "resolved_other", "comment": "This alert is resolved" } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "description": "IDs of alerts that were updated.", "items": { "type": "string" } }, "examples": { "example-1": { "value": { "reply": { "alerts_ids": [ 104173820, 574203823, 395720183 ] } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors. For example, test@test.com is not a valid Cortex XDR email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "description": "Update one or more alerts. You can update up to 100 alerts per request. Missing fields are ignored.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**" } }, "/public_api/v1/alerts/insert_cef_alerts": { "post": { "operationId": "postInsertCefAlerts", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Insert CEF Alerts", "description": "Upload alerts in CEF format from external alert sources. After you map CEF alert fields to Cortex XDR fields, Cortex XDR displays the alerts in related incidents and views.\nYou can send 600 alerts per minute.\n\nRequired license: **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "alerts": [ "CEF:0|Check Point|VPN-1 & FireWall-1|Check Point|Log|microsoft-ds|Unknown|act=AcceptdeviceDirection=0 rt=1569---000 spt=5---57 dpt=4---5cs2Label=Rule Name cs2=ADPrimerylayer_name=FW_Device_blackenedSecuritylayer_uuid=07-----fc7-1a5c-71b8c match_id=1---6parent_rule=0rule_action=Accept rule_uid=8----be5cifname=bond2logid=0loguid={0x5d8c5388,0x61,0x29321fac,0xc0000022}origin=1.1.1.1originsicname=CN=DWdeviceBlackend,O=Blackend sequencenum=363version=5dst=1.1.1.1 inzone=External outzone=Internal product=VPN-1 & FireWall-1proto=6service_id=microsoft-ds src=1.1.1.1", "CEF:0|Check Point|VPN-1 & FireWall-1|Check Point|Log|Log|Unknown|act=AcceptdeviceDirection=0 rt=1569477501000 spt=63088 dpt=5985cs2Label=RuleNamelayer_name=FW_Device_blackenedSecuritylayer_uuid=07693f---e96c71b8c match_id=8----9parent_rule=0rule_action=Acceptrule_uid=ae9---70f-ab1c-1ad552c82369conn_direction=Internal ifname=bond1.12logid=0loguid={0x5d8c537d,0xbb,0x29321fac,0xc0000014}origin=1.1.1.1originsicname=CN=DWdeviceBlackend,O=Blackend sequencenum=899version=5dst=1.1.1.1 product=VPN-1 & FireWall-1 proto=6 src=1.1.1.1" ] } }, "properties": { "request_data": { "type": "object", "properties": { "alerts": { "type": "array", "description": "A list of alerts in CEF format.", "items": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "request_data": { "alerts": [ "CEF:0|Check Point|VPN-1 & FireWall-1|Check Point|Log|microsoft-ds|Unknown|act=AcceptdeviceDirection=0 rt=1569---000 spt=5---57 dpt=4---5cs2Label=Rule Name cs2=ADPrimery layer_name=FW_Device_blackenedSecuritylayer_uuid=07-----fc7-1a5c-71b8c match_id=1---6parent_rule=0rule_action=Accept rule_uid=8----be5cifname=bond2logid=0 loguid={0x5d8c5388,0x61,0x29321fac,0xc0000022}origin=1.1.1.1originsicname=CN=DWdeviceBlackend,O=Blackend sequencenum=363version=5dst=1.1.1.1 inzone=External outzone=Internal product=VPN-1 & FireWall-1 proto=6service_id=microsoft-ds src=1.1.1.1", "CEF:0|Check Point|VPN-1 & FireWall-1|Check Point|Log|Log|Unknown|act=AcceptdeviceDirection=0 rt=1569477501000 spt=63088 dpt=5985cs2Label=Rule Namelayer_name=FW_Device_blackenedSecuritylayer_uuid=07693f---e96c71b8c match_id=8----9parent_rule=0rule_action=Acceptrule_uid=ae9---70f-ab1c-1ad552c82369conn_direction=Internal ifname=bond1.12logid=0loguid=0x5d8c537d,0xbb,0x29321fac,0xc0000014}origin=1.1.1.1originsicname=CN=DWdeviceBlackend,O=Blackend sequencenum=899version=5dst=1.1.1.1 product=VPN-1 & FireWall-1 proto=6 src=1.1.1.1" ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=upload successful" } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/alerts/insert_parsed_alerts": { "post": { "operationId": "postInsertParsedAlerts", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Insert Parsed Alerts", "description": "Upload alerts from external alert sources in Cortex XDR format. Cortex XDRdisplays alerts that are parsed successfully in related incidents and views.\nYou can send 600 alerts per minute. Each request can contain a maximum of 60 alerts.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "alerts": [ { "product": "VPN & Firewall-1", "vendor": "", "local_ip": "", "local_port": "", "remote_ip": "", "remote_port": "", "event_timestamp": 1543270652000, "severity": "Low", "alert_name": "Alert Name Example", "alert_description": "Alert Description", "action_status": "Reported", "local_ip_v6": "", "remote_ip_v6": "" } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "alerts": { "type": "array", "description": "The external alerts you want to upload to Cortex XDR.", "items": { "type": "object", "properties": { "product": { "type": "string" }, "vendor": { "type": "string" }, "local_ip": { "type": "string" }, "local_port": { "type": "string" }, "remote_ip": { "type": "string" }, "remote_port": { "type": "string" }, "event_timestamp": { "type": "integer" }, "severity": { "type": "string" }, "alert_name": { "type": "string" }, "alert_description": { "type": "string" }, "action_status": { "type": "string" }, "local_ip_v6": { "type": "string" }, "remote_ip_v6": { "type": "string" } } } } } } } }, "examples": { "example-1": { "value": { "request_data": { "alerts": [ { "product": "VPN & Firewall-1", "vendor": "", "local_ip": "", "local_port": "", "remote_ip": "", "remote_port": "", "event_timestamp": 1543270652000, "severity": "Low", "alert_name": "Alert Name Example", "alert_description": "Alert Description", "action_status": "Reported", "local_ip_v6": "", "remote_ip_v6": "" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=upload successful" } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/alerts/get_alerts_pcap": { "post": { "operationId": "postGetAlertsPcap", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Retrieve PCAP Packet", "description": "Retrieve a list of alert IDs and the associated PCAP triggering packets of PAN NGFW type alerts returned when running the **Get Alerts** and **Get Extra Incident Data** APIs. Maximum result set size is 100.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ], "search_from": "0", "search_to": "5", "sort": { "field": "severity", "keyword": "asc" } } }, "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "description": "Identifies the alert field the filter is matching. Filters are based on the following keywords:\r\n- `alert_id_list`: List of integers of the Alert ID\r\n- `alert_source`: List of strings of the Alert source\r\n- `severity`: List of strings of the Alert severity\r\n- `creation_time`: Integer of the Creation time", "enum": [ "alert_id_list", "alert_source", "severity", "creation_time" ] }, "operator": { "description": "String that identifies the comparison operator you want to use for this filter. Values keywords:\r\n`in`: \r\n- `alert_id`, `alert_source`, and `severity`.\r\n`gte` or `lte`: \r\n- `creation_time`.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "integer" ], "description": "Value that this filter must match. The contents of this field will differ depending on the alert field that you specified for this filter:\r\n- `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.\r\n- `alert_id_list`: List of integers. Each item in the list must be an alert ID.\r\n- `severity`: Valid values are `low`, `medium`, `high`, `critical`, `informational`, `unknown`.", "items": { "type": [ "integer", "string" ] } } }, "required": [ "field", "operator", "value" ] } }, "search_from": { "type": "string", "description": "An integer representing the starting offset within the query result set from which you want alerts returned.\r\nAlerts 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": { "type": "string", "description": "An integer representing the end offset within the result set after which you do not want alerts returned.\r\nAlerts 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": { "type": "object", "description": "Identifies the sort order for the result set. By default the sort is defined as creation_time, DESC.", "properties": { "field": { "description": "The field you want to sort by.", "enum": [ "creation_time", "severity" ] }, "keyword": { "description": "Whether to sort in ascending or descending order.", "enum": [ "asc", "desc" ] } }, "required": [ "field", "keyword" ] } } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ], "search_from": 0, "search_to": 5, "sort": { "field": "severity", "keyword": "asc" } } } } } } }, "description": "Note: You can send a request to retrieve either all or filtered results." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "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": { "type": "integer", "description": "Number of alerts actually returned as result." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "pcap_data": { "type": "string", "description": "For alerts without PCAP data an empty string is returned." } } } } } } } }, "examples": { "example-1": { "value": { "reply": [ { "id": 283839, "pcap_data": "" }, { "id": 319541, "pcap_data": "" } ] } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v2/alerts/get_alerts_multi_events": { "post": { "summary": "Get Alerts Multi-Events v2", "tags": [ "Incident Management" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "total_count": 1, "result_count": 1, "alerts": [ { "agent_os_sub_type": "", "fw_app_category": null, "fw_app_id": null, "fw_app_subcategory": null, "fw_app_technology": null, "category": "", "causality_actor_process_command_line": [ "" ], "causality_actor_process_image_md5": [ "" ], "causality_actor_process_image_name": [ "" ], "causality_actor_process_image_path": [ "" ], "causality_actor_process_image_sha256": [ "" ], "causality_actor_process_signature_status": [ "Signed" ], "causality_actor_process_signature_vendor": [ "" ], "causality_actor_causality_id": [ "" ], "identity_sub_type": null, "identity_type": null, "operation_name": null, "project": null, "cloud_provider": null, "referenced_resource": null, "resource_sub_type": null, "resource_type": null, "cluster_name": null, "container_id": null, "contains_featured_host": [ "NO" ], "contains_featured_ip": [ "NO" ], "contains_featured_user": [ "NO" ], "action_country": [ "UNKNOWN" ], "description": "The user domain\\username enabled a default account. The default account enabled: domain\\username", "fw_interface_to": null, "dns_query_name": null, "agent_device_domain": null, "fw_email_recipient": null, "fw_email_sender": null, "fw_email_subject": null, "events": null, "event_type": [ "" ], "is_whitelisted": false, "action_file_macro_sha256": null, "action_file_md5": null, "action_file_name": null, "action_file_path": null, "action_file_sha256": null, "fw_device_name": null, "fw_rule_id": null, "fw_rule": null, "fw_serial_number": null, "agent_fqdn": null, "agent_os_type": "", "image_name": null, "actor_process_image_name": [ "" ], "actor_process_command_line": [ "" ], "actor_process_image_md5": [ "" ], "actor_process_image_path": [ "" ], "actor_process_os_pid": [ 996 ], "actor_process_image_sha256": [ "" ], "actor_process_signature_status": [ "Signed" ], "actor_process_signature_vendor": [ "" ], "actor_thread_thread_id": [ 7452 ], "fw_is_phishing": [ "N/A" ], "action_local_ip": null, "action_local_port": null, "fw_misc": null, "mitre_tactic_id_and_name": [ "", "" ], "mitre_technique_id_and_name": [ "", "" ], "module_id": null, "fw_vsys": null, "os_actor_process_command_line": [ "" ], "os_actor_thread_thread_id": [ 7205 ], "os_actor_process_image_name": [ "" ], "os_actor_process_os_pid": [ 996 ], "os_actor_process_image_sha256": [ "" ], "os_actor_process_signature_status": [ "Signed" ], "os_actor_process_signature_vendor": [ "" ], "os_actor_effective_username": null, "action_process_signature_status": [ "N/A" ], "action_process_signature_vendor": null, "action_registry_data": null, "action_registry_full_key": null, "action_external_hostname": null, "action_remote_ip": null, "action_remote_port": null, "matching_service_rule_id": "", "fw_interface_from": null, "starred": true, "action_process_image_command_line": null, "action_process_image_name": null, "action_process_image_sha256": null, "fw_url_domain": null, "user_agent": null, "fw_xff": null, "external_id": "", "severity": "low", "matching_status": "MATCHED", "end_match_attempt_ts": null, "local_insert_ts": 1673372647792, "last_modified_ts": null, "bioc_indicator": null, "attempt_counter": 0, "bioc_category_enum_key": null, "case_id": 9629, "deduplicate_tokens": null, "filter_rule_id": null, "agent_version": "", "agent_ip_addresses_v6": null, "agent_data_collection_status": null, "agent_is_vdi": false, "agent_install_type": "STANDARD", "agent_host_boot_time": [ 1669128165772 ], "event_sub_type": [ 1 ], "association_strength": [ 50 ], "dst_association_strength": null, "story_id": null, "event_id": [ "" ], "event_timestamp": [ 1662199363118 ], "actor_process_instance_id": [ "" ], "actor_process_causality_id": [ "" ], "actor_causality_id": [ "" ], "causality_actor_process_execution_time": [ 1669528171295 ], "action_registry_key_name": null, "action_registry_value_name": null, "action_local_ip_v6": null, "action_remote_ip_v6": null, "action_process_instance_id": null, "action_process_causality_id": null, "os_actor_process_instance_id": [ "" ], "os_actor_process_image_path": [ "" ], "os_actor_process_causality_id": [ "" ], "os_actor_causality_id": null, "dst_agent_id": [ "" ], "dst_causality_actor_process_execution_time": null, "dst_action_external_hostname": null, "dst_action_country": null, "dst_action_external_port": null, "is_pcap": false, "alert_type": "Unclassified", "resolution_status": "STATUS_010_NEW", "resolution_comment": null, "dynamic_fields": null, "tags": [ "ET:DESKTOP-FCCIPAN", "EG:k8s agents", "EG:windows" ], "dss_job_title": null, "dss_department": null, "dss_country": null, "dss_groups": null, "alert_id": "", "detection_timestamp": 1569159363318, "name": "A user enabled the Windows DefaultAccount", "endpoint_id": "", "host_ip": [ "" ], "host_name": "", "action": "DETECTED", "original_tags": [ "EG:k8s agents", "EG:windows", "ET:DESKTOP-FCCIPAN" ], "user_name": [ "" ], "mac_addresses": null, "source": null, "action_pretty": "Detected", "variation_rule_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" } ] } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "total_count": { "type": "integer", "description": "The number of total results returned by this filter without paging. If the filter returns more than 9,999 the total_count value returned will be 9.999. You can use paging to view the entire set of data." }, "result_count": { "type": "integer", "description": "The number of alerts actually returned as results." }, "alerts": { "type": "array", "description": "A list of alerts.", "items": { "type": "object", "properties": { "agent_os_sub_type": { "type": "string" }, "fw_app_category": { "nullable": true }, "fw_app_id": { "nullable": true }, "fw_app_subcategory": { "nullable": true }, "fw_app_technology": { "nullable": true }, "category": { "type": "string" }, "causality_actor_process_command_line": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_image_md5": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_image_name": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_image_path": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_image_sha256": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_signature_status": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_signature_vendor": { "type": "array", "items": { "type": "string" } }, "causality_actor_causality_id": { "type": "array", "items": { "type": "string" } }, "identity_sub_type": { "nullable": true }, "identity_type": { "nullable": true }, "operation_name": { "nullable": true }, "project": { "nullable": true }, "cloud_provider": { "nullable": true }, "referenced_resource": { "nullable": true }, "resource_sub_type": { "nullable": true }, "resource_type": { "nullable": true }, "cluster_name": { "nullable": true }, "container_id": { "nullable": true }, "contains_featured_host": { "type": "array", "items": { "type": "string" } }, "contains_featured_ip": { "type": "array", "items": { "type": "string" } }, "contains_featured_user": { "type": "array", "items": { "type": "string" } }, "action_country": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "fw_interface_to": { "nullable": true }, "dns_query_name": { "nullable": true }, "agent_device_domain": { "nullable": true }, "fw_email_recipient": { "nullable": true }, "fw_email_sender": { "nullable": true }, "fw_email_subject": { "nullable": true }, "event_type": { "type": "array", "items": { "type": "string" } }, "is_whitelisted": { "type": "boolean" }, "action_file_macro_sha256": { "nullable": true }, "action_file_md5": { "nullable": true }, "action_file_name": { "nullable": true }, "action_file_path": { "nullable": true }, "action_file_sha256": { "nullable": true }, "fw_device_name": { "nullable": true }, "fw_rule_id": { "nullable": true }, "fw_rule": { "nullable": true }, "fw_serial_number": { "nullable": true }, "agent_fqdn": { "nullable": true }, "agent_os_type": { "type": "string" }, "image_name": { "nullable": true }, "actor_process_image_name": { "type": "array", "items": { "type": "string" } }, "actor_process_command_line": { "type": "array", "items": { "type": "string" } }, "actor_process_image_md5": { "type": "array", "items": { "type": "string" } }, "actor_process_image_path": { "type": "array", "items": { "type": "string" } }, "actor_process_os_pid": { "type": "array", "items": { "type": "integer" } }, "actor_process_image_sha256": { "type": "array", "items": { "type": "string" } }, "actor_process_signature_status": { "type": "array", "items": { "type": "string" } }, "actor_process_signature_vendor": { "type": "array", "items": { "type": "string" } }, "actor_thread_thread_id": { "type": "array", "items": { "type": "integer" } }, "fw_is_phishing": { "type": "array", "items": { "type": "string" } }, "action_local_ip": { "nullable": true }, "action_local_port": { "nullable": true }, "fw_misc": { "nullable": true }, "mitre_tactic_id_and_name": { "type": "array", "items": { "type": "string" } }, "mitre_technique_id_and_name": { "type": "array", "items": { "type": "string" } }, "module_id": { "nullable": true }, "fw_vsys": { "nullable": true }, "os_actor_process_command_line": { "type": "array", "items": { "type": "string" } }, "os_actor_thread_thread_id": { "type": "array", "items": { "type": "integer" } }, "os_actor_process_image_name": { "type": "array", "items": { "type": "string" } }, "os_actor_process_os_pid": { "type": "array", "items": { "type": "integer" } }, "os_actor_process_image_sha256": { "type": "array", "items": { "type": "string" } }, "os_actor_process_signature_status": { "type": "array", "items": { "type": "string" } }, "os_actor_process_signature_vendor": { "type": "array", "items": { "type": "string" } }, "os_actor_effective_username": { "nullable": true }, "action_process_signature_status": { "type": "array", "items": { "type": "string" } }, "action_process_signature_vendor": { "nullable": true }, "action_registry_data": { "nullable": true }, "action_registry_full_key": { "nullable": true }, "action_external_hostname": { "nullable": true }, "action_remote_ip": { "nullable": true }, "action_remote_port": { "nullable": true }, "matching_service_rule_id": { "type": "string" }, "fw_interface_from": { "nullable": true }, "starred": { "type": "boolean" }, "action_process_image_command_line": { "nullable": true }, "action_process_image_name": { "nullable": true }, "action_process_image_sha256": { "nullable": true }, "fw_url_domain": { "nullable": true }, "user_agent": { "nullable": true }, "fw_xff": { "nullable": true }, "external_id": { "type": "string" }, "severity": { "type": "string" }, "matching_status": { "type": "string" }, "end_match_attempt_ts": { "nullable": true }, "local_insert_ts": { "type": "integer" }, "last_modified_ts": { "nullable": true }, "bioc_indicator": { "nullable": true }, "attempt_counter": { "type": "integer" }, "bioc_category_enum_key": { "nullable": true }, "case_id": { "type": "integer" }, "deduplicate_tokens": { "nullable": true }, "filter_rule_id": { "nullable": true }, "agent_version": { "type": "string" }, "agent_ip_addresses_v6": { "nullable": true }, "agent_data_collection_status": { "nullable": true }, "agent_is_vdi": { "type": "boolean" }, "agent_install_type": { "type": "string" }, "agent_host_boot_time": { "type": "array", "items": { "type": "integer" } }, "event_sub_type": { "type": "array", "items": { "type": "integer" } }, "association_strength": { "type": "array", "items": { "type": "integer" } }, "dst_association_strength": { "nullable": true }, "story_id": { "nullable": true }, "event_id": { "type": "array", "items": { "type": "string" } }, "event_timestamp": { "type": "array", "items": { "type": "integer" } }, "actor_process_instance_id": { "type": "array", "items": { "type": "string" } }, "actor_process_causality_id": { "type": "array", "items": { "type": "string" } }, "actor_causality_id": { "type": "array", "items": { "type": "string" } }, "causality_actor_process_execution_time": { "type": "array", "items": { "type": "integer" } }, "action_registry_key_name": { "nullable": true }, "action_registry_value_name": { "nullable": true }, "action_local_ip_v6": { "nullable": true }, "action_remote_ip_v6": { "nullable": true }, "action_process_instance_id": { "nullable": true }, "action_process_causality_id": { "nullable": true }, "os_actor_process_instance_id": { "type": "array", "items": { "type": "string" } }, "os_actor_process_image_path": { "type": "array", "items": { "type": "string" } }, "os_actor_process_causality_id": { "type": "array", "items": { "type": "string" } }, "os_actor_causality_id": { "nullable": true }, "dst_agent_id": { "type": "array", "items": { "type": "string" } }, "dst_causality_actor_process_execution_time": { "nullable": true }, "dst_action_external_hostname": { "nullable": true }, "dst_action_country": { "nullable": true }, "dst_action_external_port": { "nullable": true }, "is_pcap": { "type": "boolean" }, "alert_type": { "type": "string" }, "resolution_status": { "type": "string" }, "resolution_comment": { "nullable": true }, "dynamic_fields": { "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "alert_id": { "type": "string" }, "detection_timestamp": { "type": "integer" }, "name": { "type": "string" }, "endpoint_id": { "type": "string" }, "host_ip": { "type": "array", "items": { "type": "string" } }, "host_name": { "type": "string" }, "action": { "type": "string" }, "original_tags": { "type": "array", "items": { "type": "string" } }, "user_name": { "type": "array", "items": { "type": "string" } }, "mac_addresses": { "nullable": true }, "source": { "nullable": true }, "action_pretty": { "type": "string" }, "variation_rule_id": { "type": "string" } } } } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "operationId": "post-public_api-v2-alerts-get_alerts_multi_events", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "description": "Get a list of alerts with multiple events.\n- The response is concatenated using AND condition (OR is not supported).\n- The maximum result set size is 100.\n- Offset is the zero-based number of alerts from the start of the result set.\n\nCortex XDR displays in the API response whether a PAN NGFW type alert contains a PCAP triggering packet. Use the **Retrieve PCAP Packet** API to retrieve a list of alert IDs and their associated PCAP data.\n\nNote: You can send a request to retrieve either all or filtered results.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "filters": [ { "field": "alert_id_list", "operator": "in", "value": [ 50015265100 ] }, { "field": "alert_source", "operator": "in", "value": [ "XDR Analytics BIOC" ] }, { "field": "severity", "operator": "in", "value": [ "low" ] }, { "field": "creation_time", "operator": "lte", "value": 1687977251785 } ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.\n\nAn empty dictionary returns all results.", "properties": { "filters": { "anyOf": [ { "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "alert_id_list", "alert_source", "severity", "creation_time", "server_creation_time" ], "description": "Alert field the filter is matching. Filters are based on the following keywords:\n- `alert_id_list`: List of integers of the alert ID\n- `alert_source`: List of strings of the alert source\n- `severity`: List of strings of the alert severity\n- `creation_time`: Timestamp of the creation time\n- `server_creation_time`: Timestamp of when Cortex XDR created the alert" }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "description": "Identifies the comparison operator you want to use for this filter. Possible values:\n`in`\n- permitted for `alert_id`, `alert_source`, and `severity`\n- `gte` / `lte`\n- Permitted only for `creation_time'" }, "value": { "type": [ "array", "integer" ], "description": "Value that the filter must match. The contents of this field differ depending on the alert field that you specified for this filter.", "items": { "type": [ "integer", "string" ], "enum": [ "low", "medium", "high", "critical", "informational" ] } } } } } ], "description": "Array of filter fields.", "type": "array" } } } } }, "examples": { "Example 1": { "value": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ] } } } } } } } } }, "/public_api/v1/alerts/get_alerts_multi_events": { "post": { "operationId": "postGetAlertsMultiEvents", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Get Alerts Multi-Events v1", "description": "**Note: ** This endpoint is legacy. Use the [Get Alerts Multi-Events v2](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/incident-management#post-public_api-v2-alerts-get_alerts_multi_events) endpoint.\n\nGet a list of alerts with multiple events.\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 100.\n- Offset is the zero-based number of alerts from the start of the result set.\nCortex XDR displays in the APIs response whether an PAN NGFW type alert contains a PCAP triggering packet. Use the Retrieve PCAP Packet API to retrieve a list of alert IDs and their associated PCAP data.\n\nNote: You can send a request to retrieve either all or filtered results.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ], "search_from": 0, "search_to": 5, "sort": { "field": "severity", "keyword": "asc" } } }, "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "enum": [ "alert_id_list", "alert_source", "severity", "creation_time", "server_creation_time", "external_id_list" ], "description": "Identifies the alert field the filter is matching. Filters are based on the following keywords:\r\n- `alert_id_list`: List of integers representing the alert IDs.\r\n- `alert_source`: List of strings representing the alert sources.\r\n- `severity`: List of strings representing the alert severities.\r\n- `creation_time`: Timestamp of the alert creation time.\r\n- `server_creation_time`: Timestamp of when Cortex XDR created the alert.\r\n- `external_id_list`: List of external IDs." }, "operator": { "enum": [ "in", "gte", "lte" ], "description": "Identifies the comparison operator you want to use for this filter. Valid keywords are:\r\n`in`: \r\n- `alert_id_list`, `alert_source`, `severity`, and `external_id_list`.\r\n`gte` / `lte`\r\n- `creation_time`." }, "value": { "description": "Value that this filter must match. The contents of this field will differ depending on the alert field that you specified for this filter:\r\n- `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.\r\n- `alert_id_list`: Array of integers. Each item in the list must be an alert ID.\r\n- `severity`: Valid values are `low`, `medium`, `high`, `critical`.\r\n- `external_id_list`: Array of strings.", "type": [ "integer", "array", "string" ], "items": { "type": [ "string", "integer" ] } } } } }, "search_from": { "type": "integer", "description": "An integer representing the starting offset within the query result set from which you want alerts returned.\r\nAlerts 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": { "type": "integer", "description": "An integer representing the end offset within the result set after which you do not want alerts returned.\r\nAlerts 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": { "type": "object", "description": "Identifies the sort order for the result set. By default the sort is defined as *creation_time*, *desc*.", "required": [ "keyword" ], "properties": { "field": { "enum": [ "severity", "creation_time" ], "description": "Identifies how to sort the result set, either according to severity or creation time. " }, "keyword": { "enum": [ "asc", "desc" ], "description": "Defines whether to sort the results in ascending (asc) or descending (desc) order." } } } } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "severity", "operator": "in", "value": [ "medium", "high" ] } ], "search_from": 0, "search_to": 5, "sort": { "field": "severity", "keyword": "asc" } } } } } } }, "description": "If no parameters are included, all results will be returned." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "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": { "type": "integer", "description": "Number of alerts actually returned as result." }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/alert" } }, "alert_id": { "type": "string" }, "detection_timestamp": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string" }, "endpoint_id": { "type": "string" }, "description": { "type": "string" }, "host_ip": { "type": "array", "items": { "type": "string" } }, "host_name": { "type": "string" }, "source": { "type": "string" }, "action": { "type": "string" }, "action_pretty": { "type": "string" }, "malicious_urls": { "type": "array", "description": "Malicious URL/s that have been detected in the destination or content of the accessed web page.", "items": { "type": "string" } } } }, "examples": { "Success response": { "value": { "reply": { "total_count": 45, "result_count": 1, "alerts": [ { "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_device_domain": null, "agent_fqdn": "test", "agent_os_type": "Windows", "agent_os_sub_type": "", "agent_data_collection_status": true, "mac": null, "mac_address": [ "" ], "agent_is_vdi": null, "contains_featured_host": false, "contains_featured_user": false, "contains_featured_ip": false, "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": "", "actor_process_image_path": "c:\\\\virus.exe", "actor_process_image_name": "virus.exe", "actor_process_command_line": "c:\\\\virus.exe", "actor_process_signature_status": "N/A", "actor_process_signature_vendor": null, "actor_process_image_sha256": "", "actor_process_image_md5": null, "actor_process_causality_id": null, "actor_causality_id": null, "actor_process_os_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": "", "detection_timestamp": 1603279888980, "name": "Kernel Privilege Escalation", "category": "Exploit", "endpoint_id": "", "description": "Local privilege escalation prevented", "host_ip": [ "" ], "host_name": "Test", "source": "XDR Agent", "action": "BLOCKED", "action_pretty": "Prevented (Blocked)" } ] } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/featured_fields/replace_hosts": { "post": { "operationId": "postReplaceHosts", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Replace Featured Hosts", "description": "Replace the featured hosts listed in your environment.\n\nNote: Running this API will delete all existing host names.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "fields": [ { "value": "ADMIN-PC", "comment": "ADMIN-PC is a featured host" }, { "value": "CEO-PC" } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "fields": { "type": "array", "description": "An array of host names and comments.", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Defines the host name. Maximum length is 256 characters." }, "comment": { "type": "string", "description": "Represents additional information regarding the featured alert field." } }, "required": [ "value" ] } } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "fields": [ { "value": "ADMIN-PC", "comment": "ADMIN-PC is a featured host" }, { "value": "CEO-PC" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=host names successfully replaced" } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/featured_fields/replace_users": { "post": { "operationId": "postReplaceUsers", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Replace Featured Users", "description": "Replace the featured users listed in your environment.\n\nNote: Running this API will delete all existing user names.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "fields": [ { "value": "Administrator", "comment": "Administrator is a featured user" }, { "value": "System" } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "fields": { "type": "array", "description": "An array of users and comments.", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Defines the user name. Maximum length is 256 characters.", "maxLength": 256 }, "comment": { "type": "string", "description": "Additional information regarding the featured alert field." } }, "required": [ "value" ] } } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "fields": [ { "value": "Administrator", "comment": "Administrator is a featured user" }, { "value": "System" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true = User names successfully replaced." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/featured_fields/replace_ip_addresses": { "post": { "operationId": "postReplaceIpAddresses", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Replace Featured IP Addresses", "description": "Replace the featured IP addresses listed in your environment.\n\nNote: Running this API will delete all existing IP addresses.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "fields": [ { "value": "1.2.3.4", "comment": "A single featured IP" }, { "value": "192.111.1.0-192.111.1.255", "comment": "Featured IP range" }, { "value": "7.7.7.7/16", "comment": "Featured CIDR" } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "fields": { "type": "array", "description": "An array of IP addresses and comments.", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Define the IP address. Maximum length is 256 characters, IP address can be a single IP address, range, or CIDR.", "maxLength": 256 }, "comment": { "type": "string", "description": "String that represents additional information regarding the featured IP address." } }, "required": [ "value" ] } } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "fields": [ { "value": "1.2.3.4", "comment": "A single featured IP" }, { "value": "192.111.1.0-192.111.1.255", "comment": "Featured IP range" }, { "value": "7.7.7.7/16", "comment": "Featured CIDR" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=IP addresses successfully replaced." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/featured_fields/replace_ad_groups": { "post": { "operationId": "postReplaceAdGroups", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Incident Management" ], "summary": "Replace Featured Active Directory Groups", "description": "Replace the featured active directory groups and organizational units listed in your environment.\n\nNote: Running this API will delete all existing active directory groups.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "fields": [ { "value": "domain/administrators-group", "type": "group", "comment": "Administrators-group is a featured AD group" }, { "value": "dev", "type": "OU" } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "fields": { "type": "array", "description": "An array of active directory groups and organizational units and comments.", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "String value that defines the active directory or organizational unit name. Maximum length is 256 characters.\nAn active directory name must be formated as: DOMAIN/GROUPNAME" }, "type": { "type": "string", "description": "Define whether you want to replace an active directory group or organizational unit.\nValid values are either `group` or `OU`.\nIf no value is defined, `group` is sent by default.", "enum": [ "group", "OU" ], "default": "group" }, "comment": { "type": "string", "description": "String that represents additional information regarding the featured active directory group." } }, "required": [ "value" ] } } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "fields": [ { "value": "domain/administrators-group", "type": "group", "comment": "Administrators-group is a featured AD group" }, { "value": "dev", "type": "OU" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=Active directory group successfully replaced." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/endpoints/get_endpoints": { "post": { "operationId": "postGetEndpoints", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get all Endpoints", "description": "Gets a list of all of your endpoints. The response is concatenated using AND condition (OR is not supported).\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": {} } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "array", "items": { "type": "object", "properties": { "agent_id": { "type": "string" }, "agent_status": { "type": "string" }, "operational_status": { "type": "string" }, "host_name": { "type": "string" }, "agent_type": { "type": "string" }, "ip": { "type": "array", "items": { "type": "string" } }, "last_seen": { "type": "integer" }, "tags": { "type": "object", "properties": { "server_tags": { "type": "array", "items": { "type": "object", "properties": {} } }, "endpoint_tags": { "type": "array", "items": { "type": "object", "properties": {} } } } }, "users": { "type": "array", "items": { "type": "string" } } } } } }, "x-examples": { "Example 1": { "reply": [ { "agent_id": "", "agent_status": "DISCONNECTED", "operational_status": "PROTECTED", "host_name": "", "agent_type": "Workstation", "ip": [ "" ], "last_seen": 1678012587521, "tags": { "server_tags": [], "endpoint_tags": [] }, "users": [ "user" ] } ] } } }, "examples": { "example-1": { "value": { "reply": [ { "agent_id": "", "agent_status": "DISCONNECTED", "operational_status": "PROTECTED", "host_name": "", "agent_type": "Workstation", "ip": [ "" ], "last_seen": 1678012587521, "tags": { "server_tags": [], "endpoint_tags": [] }, "users": [ "user" ] } ] } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/endpoints/get_endpoint": { "post": { "summary": "Get Endpoint", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Endpoint Management" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "total_count": 1, "result_count": 1, "endpoints": [ { "endpoint_id": "", "endpoint_name": "", "endpointTags": "", "endpoint_type": "", "endpoint_status": "CONNECTED", "os_type": "AGENT_OS_WINDOWS", "os_version": "8.0.xxx", "ip": [ "" ], "ipv6": [], "public_ip": "", "users": [ "XDR" ], "domain": "WORKGROUP", "alias": "", "first_seen": 1606218761377, "last_seen": 1606218769163, "content_version": "", "installation_package": "XDR", "active_directory": null, "install_date": 1606218762089, "endpoint_version": "", "is_isolated": "AGENT_UNISOLATED", "isolated_date": null, "group_name": [], "operational_status": "PARTIALLY_PROTECTED", "operational_status_description": "[{\"name\": \"generalStatus\", \"error_code\": 10004}]", "scan_status": "SCAN_STATUS_NONE", "content_release_timestamp": 1636285746000, "last_content_update_time": 1636381954285, "content_status": "up_to_date", "operating_system": "Debian 10.11", "mac_address": [ "42:00:00:00:00:00" ], "assigned_prevention_policy": "Linux Default", "assigned_extensions_policy": "" } ] } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "total_count": { "type": "integer", "description": "Number of total results of this filter without paging." }, "result_count": { "type": "integer", "description": "Number of endpoints actually returned as result." }, "endpoints": { "type": "array", "description": "A list of endpoints.", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string" }, "endpoint_name": { "type": "string" }, "endpointTags": { "type": "string" }, "endpoint_type": { "type": "string" }, "endpoint_status": { "type": "string" }, "os_type": { "type": "string" }, "os_version": { "type": "string" }, "ip": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "object" } }, "public_ip": { "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string" }, "alias": { "type": "string" }, "first_seen": { "type": "integer" }, "last_seen": { "type": "integer" }, "content_version": { "type": "string" }, "installation_package": { "type": "string" }, "active_directory": { "nullable": true }, "install_date": { "type": "integer" }, "endpoint_version": { "type": "string" }, "is_isolated": { "type": "string" }, "isolated_date": { "nullable": true }, "group_name": { "type": "array", "items": { "type": "object" } }, "operational_status": { "type": "string" }, "operational_status_description": { "type": "string" }, "scan_status": { "type": "string" }, "content_release_timestamp": { "type": "integer" }, "last_content_update_time": { "type": "integer" }, "content_status": { "type": "string" }, "operating_system": { "type": "string" }, "mac_address": { "type": "array", "items": { "type": "string" } }, "assigned_prevention_policy": { "type": "string" }, "assigned_extensions_policy": { "type": "string" } } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "total_count": 0, "result_count": 0, "endpoints": [ { "endpoint_id": "string", "endpoint_name": "string", "endpointTags": "string", "endpoint_type": "string", "endpoint_status": "string", "os_type": "string", "os_version": "string", "ip": [ "string" ], "ipv6": [ {} ], "public_ip": "string", "users": [ "string" ], "domain": "string", "alias": "string", "first_seen": 0, "last_seen": 0, "content_version": "string", "installation_package": "string", "active_directory": null, "install_date": 0, "endpoint_version": "string", "is_isolated": "string", "isolated_date": null, "group_name": [ {} ], "operational_status": "string", "operational_status_description": "string", "scan_status": "string", "content_release_timestamp": 0, "last_content_update_time": 0, "content_status": "string", "operating_system": "string", "mac_address": [ "string" ], "assigned_prevention_policy": "string", "assigned_extensions_policy": "string" } ] } } }, "Example 2": { "value": { "reply": { "total_count": 1, "result_count": 1, "endpoints": [ { "endpoint_id": "", "endpoint_name": "", "endpointTags": "", "endpoint_type": "", "endpoint_status": "CONNECTED", "os_type": "AGENT_OS_WINDOWS", "os_version": "8.0.xxx", "ip": [ "" ], "ipv6": [], "public_ip": "", "users": [ "XDR" ], "domain": "WORKGROUP", "alias": "", "first_seen": 1606218761377, "last_seen": 1606218769163, "content_version": "", "installation_package": "XDR", "active_directory": null, "install_date": 1606218762089, "endpoint_version": "", "is_isolated": "AGENT_UNISOLATED", "isolated_date": null, "group_name": [], "operational_status": "PARTIALLY_PROTECTED", "operational_status_description": "[{\"name\": \"generalStatus\", \"error_code\": 10004}]", "scan_status": "SCAN_STATUS_NONE", "content_release_timestamp": 1636285746000, "last_content_update_time": 1636381954285, "content_status": "up_to_date", "operating_system": "Debian 10.11", "mac_address": [ "42:00:00:00:00:00" ], "assigned_prevention_policy": "Linux Default", "assigned_extensions_policy": "" } ] } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "operationId": "post-public_api-v1-endpoints-get_endpoint", "description": "Gets a list of filtered endpoints.\n- The response is concatenated using AND condition (OR is not supported).\n- The maximum result set size is 100.\n- Offset is the zero-based number of endpoints from the start of the result set.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "search_from": 0, "search_to": 1, "sort": { "field": "endpoint_id", "keyword": "ASC" }, "filters": [ { "field": "group_name", "operator": "in", "value": [ "Test-Group-01" ] }, { "field": "endpoint_status", "operator": "in", "value": [ "disconnected" ] }, { "field": "dist_name", "operator": "in", "value": [ "papi-test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success", "canceled", "error" ] } ] } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.\n\nAn empty dictionary returns all results.", "properties": { "filters": { "type": "array", "description": "Array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `endpoint_status`: Status of the endpoint ID.\n- `dist_name`: Distribution / Installation Package name.\n- `first_seen`: When the agent was first seen.\n- `last_seen`: When the agent was last seen.\n- `ip_list`: List of IP addresses.\n- `group_name`: Group name the agent belongs to.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `isolate`: If the endpoint was isolated.\n- `hostname`: Host name.\n- `public_ip_list`: Public IP addresses that correlate to the last IPv4 address from which the XDR agent connected (know as `Last Origin IP`).", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "first_seen", "last_seen", "ip_list", "group_name", "platform", "alias", "isolate", "hostname", "public_ip_list" ] }, "operator": { "type": "string", "description": "Identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `public_ip_list`: List of strings.\n- `endpoint_status`: `connected`, `disconnected`, `lost`, or `uninstalled`\n- `ip_list`: List of strings. For example: \"192.168.5.12\"\n- `platform`: `windows`, `linux`, `macos`, `android`\n- `isolate`: `isolated` or `unisolated`\n- `scan_status`: `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`\n`gte` / `lte`\n- `first_seen` and `last_seen`: Timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte", "eq" ] }, "value": { "type": [ "string", "array" ], "description": "Value that this filter must match. Valid keywords:\r\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `public_ip_list`: List of strings.\r\n- `endpoint_status`: String. Permitted values are: `connected`, `disconnected`, `lost`, or `uninstalled`\r\n- `ip_list`: List of strings.\r\n- `platform`: String. Permitted values are: `windows`, `linux`, `macos`, `android`.\r\n- `isolate`: String. Permitted values are: `isolated` or `unisolated`.\r\n- `scan_status`: String. Permitted values are: `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\r\n- `first_seen` and `last_seen`: Integer. Timestamp epoch milliseconds.", "items": { "type": "string" } } } } }, "search_from": { "type": "integer", "description": "Represents the start offset within the query result set from which you want endpoints returned.\n\nEndpoints are returned as a zero-based list. Any endpoint indexed less than this value is not returned in the final result set and defaults to zero." }, "search_to": { "type": "integer", "description": "Represents the end offset within the result set after which you do not want endpoints returned.\n\nEndpoint in the endpoint list that is indexed higher than this value is not returned in the final results set. Defaults to 100, which returns all endpoints to the end of the list." }, "sort": { "type": "object", "description": "Identifies the sort order for the result set.", "properties": { "field": { "type": "string", "enum": [ "endpoint_id", "first_seen", "last_seen", "scan_status" ], "default": "first_seen", "description": "Identifies the field you want to sort by. Case-sensitive." }, "keyword": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "description": "Whether you want to sort in ascending (`ASC`) or descending (`DESC`) order. Case-sensitive." } } } } } } }, "examples": { "Request filtered results": { "value": { "request_data": { "search_from": 0, "search_to": 1, "sort": { "field": "endpoint_id", "keyword": "asc" }, "filters": [ { "field": "endpoint_status", "operator": "eq", "value": "disconnected" }, { "field": "dist_name", "operator": "in", "value": [ "papi-test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success", "canceled", "error" ] } ] } } }, "Request all results": { "value": { "request_data": {} } } } } }, "description": "You can send a request to retrieve either all or filtered results." } } }, "/public_api/v1/endpoints/update_agent_name": { "post": { "operationId": "postUpdateAgentName", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Set an Endpoint Alias", "description": "Set or modify an Alias field for your endpoints.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } }, "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `endpoint_status`: Status of the endpoint ID.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `group_name`: Group name the agent belongs to.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `isolate`: If the endpoint was isolated.\n- `hostname`: Hostname", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "ip_list", "group_name", "platform", "alias", "isolate", "hostname" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings.\n- `endpoint_status`: Permitted values are `connected` or `disconnected`\n- `ip_list`: List of strings, for example 192.168.5.12.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "string" ], "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `dist_name`, `hostname`, `alias`, `group_name`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected` or `disconnected`\n- `ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "alias": { "type": "string", "description": "The alias name you want to set or modify.\n\nNote: If you send an empty field, the current alias name is deleted." } } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "alias": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=The alias name was set or modified successfully." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/endpoints/get_policy": { "post": { "operationId": "postGetPolicy", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get Policy", "description": "Get the policy name for a specific endpoint.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "endpoint_id": "" } } }, "properties": { "request_data": { "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID." } }, "required": [ "endpoint_id" ] } } }, "examples": { "example-1": { "value": { "request_data": { "endpoint_id": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "policy_name": "Windows Default" } } }, "properties": { "reply": { "type": "object", "properties": { "policy_name": { "type": "string", "description": "Name of the policy allocated with the endpoint." } } } } }, "examples": { "example-1": { "value": { "reply": { "policy_name": "Windows Default" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/endpoints/terminate_process": { "post": { "summary": "Terminate the specified agent process", "tags": [ "Endpoint Management" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "group_action_id": { "type": "integer" } } } }, "x-examples": { "Example 1": { "reply": { "group_action_id": 123456789 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, ID, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } }, "operationId": "post-public_api-v1-endpoints-terminate_process", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "agent_id", "instance_id" ], "properties": { "agent_id": { "type": "string" }, "instance_id": { "type": "string" }, "process_name": { "type": "string" }, "incident_id": { "type": "string" } } } } }, "examples": { "Example 1": { "value": { "request_data": { "agent_id": "46c3875799bd4b609ebcbe91bda61458", "instance_id": "AdrNHXdJutcAAA78AAAAAA==", "process_name": "My Awesome Process" } } } } } } }, "x-internal": true } }, "/public_api/v1/endpoints/terminate_causality": { "post": { "summary": "Terminate a process by causality ID", "tags": [ "Endpoint Management" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "group_action_id": { "type": "string" } } } }, "x-examples": { "Example 1": { "reply": { "group_action_id": " (int > 0)" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, ID, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/reply" } } } } }, "operationId": "post-public_api-v1-endpoints-terminate_causality", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "agent_id": "", "causality_id": "", "process_name": " (string, null, omitted)", "incident_id": " (string, null, omitted)" } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "agent_id", "causality_id" ], "properties": { "agent_id": { "type": "string" }, "causality_id": { "type": "string" }, "process_name": { "type": "string" }, "incident_id": { "type": "string" } } } } }, "examples": { "Example 1": { "value": { "request_data": { "agent_id": "46c3876799cd4b609ebcbe91bda61448", "causality_id": "AdrNH5oDO6YAACWEAAAAAA==" } } } } } } }, "x-internal": true } }, "/public_api/v1/endpoints/delete": { "post": { "operationId": "postDelete", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Delete Endpoints", "description": "Delete selected endpoints in the Cortex XDR app. You can delete up to 1000 endpoints.\n\nNote: Endpoints are deleted from the Cortex XDR app web interface, however they still exist in the database.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 1000.\n- Offset is the zero-based number of incidents from the start of the result set.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ] } } }, "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "Array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs." }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings", "enum": [ "in" ] }, "value": { "type": "array", "description": "Value that this filter must match. Valid keywords:\n- `endpoint_id_list`: List of strings", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } } } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] }, "parameters": [] }, "/public_api/v1/endpoints/get_profiles": { "post": { "summary": "Get endpoint security profiles", "tags": [ "Endpoint Management", "Profiles" ], "responses": { "200": { "description": "OK. Profiles retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProfilesResponse" }, "examples": { "Example 1": { "value": { "reply": [ { "id": 1, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Default Malware Profile", "type": "MALWARE", "platform": "AGENT_OS_WINDOWS", "is_default": true, "is_global": false, "is_disabled": false, "associated_targets": [ "All endpoints" ], "usage_count": 5, "description": "Default anti-malware profile for Windows", "created_by": "system", "created_by_pretty": "Palo Alto Networks", "creation_time": 1700000000000, "modified_by": "admin@example.com", "modified_by_pretty": "Admin User", "modification_time": 1710000000000, "modules": { "malware": { "mode": "prevent" } } }, { "id": 2, "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Custom Exploit Profile", "type": "EXPLOIT", "platform": "AGENT_OS_MAC", "is_default": false, "is_global": false, "is_disabled": false, "associated_targets": [ "macOS Servers" ], "usage_count": 2, "description": null, "created_by": "admin@example.com", "created_by_pretty": "Admin User", "creation_time": 1705000000000, "modified_by": "admin@example.com", "modified_by_pretty": "Admin User", "modification_time": 1705000000000, "modules": {} } ] } } } } } }, "400": { "description": "Bad request. Possible causes:\n- `type` field is missing (`TypeIsMandatory`)\n- `type` value is not `prevention` or `extension` (`TypeNotSupported`)\n- `profile_ids` is provided but is not a list (`ProfileIDsMustBeAList`)\n- Any internal error during profile retrieval (`GeneralError`)\n", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "invalid request - operator contains is unsupported for rule_name, conditions is not supported for filtering, module_name is not supported for filtering, description is not supported for filtering, value Enabled is not valid for field status, modification_time is not supported for filtering, profiles is not supported for filtering, generating_alert_id is not supported for filtering" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "HTTP-equivalent error code" }, "err_msg": { "type": "string", "description": "Short error category string" }, "err_extra": { "type": "string", "description": "Human-readable detail explaining the specific error", "nullable": true } } } } }, "examples": { "type field not provided": { "value": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "type is mandatory" } } }, "unsupported type value": { "value": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "type 'unknown' is not supported. Valid types: ('prevention', 'extension')" } } }, "profile_ids is not a list": { "value": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "profile_ids must be a list" } } }, "internal error during profile retrieval": { "value": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "General error" } } } } } } }, "401": { "description": "Unauthorized – missing or invalid API-key headers", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "type is mandatory" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "HTTP-equivalent error code" }, "err_msg": { "type": "string", "description": "Short error category string" }, "err_extra": { "type": "string", "description": "Human-readable detail explaining the specific error", "nullable": true } } } } } } } }, "403": { "description": "Forbidden. Possible causes:\n\n- The API key does not have the `profiles_view` permission\n- The feature flag `ALPHAFEATURES_PUBLIC_API_GET_POLICIES` is disabled\n- The tenant is a secondary HA replica", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "PROFILES_PUBLIC_API_ERROR", "err_extra": "type is mandatory" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "HTTP-equivalent error code" }, "err_msg": { "type": "string", "description": "Short error category string" }, "err_extra": { "type": "string", "description": "Human-readable detail explaining the specific error", "nullable": true } } } } } } } }, "500": { "description": "Internal Server Error" } }, "operationId": "getProfiles", "description": "Returns a list of endpoint security profiles of the requested type.\nOptionally filters by a list of profile IDs.\n\n**Required permission:** `profiles_view`\n\n\n**Notes**: \n- File-Integrity-Monitoring (FIM) extension profiles are omitted when FIM is disabled for the profile's OS type.\n- `is_in_user_scope` and `at_risk` are removed from every profile object before the response is returned.", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "required": true, "description": "{api_key}" }, { "schema": { "type": "string" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": {} } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/GetProfilesRequestData" } } }, "examples": { "Fetch all prevention profiles": { "value": { "request_data": { "type": "prevention" } } }, "Fetch specific extension profiles by ID": { "value": { "request_data": { "type": "extension", "profile_ids": [ 1, 42, 99 ] } } } } } } } } }, "/public_api/v1/legacy_exceptions/get_modules": { "post": { "summary": "Get Legacy Exceptions Modules", "operationId": "get_legacy_exceptions_modules", "tags": [ "Endpoint Management" ], "description": "Get a list of supported legacy exception modules available in the tenant. Each module entry includes its `module_id`, supported `platforms`, and the `conditions_definition` schema that must be used when creating or editing a legacy exception rule for that module.\n\n**Note**: No request body required. Send an empty body.\n\n", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "{api_key}", "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " } }, { "name": "x-xdr-auth-id", "in": "header", "required": true, "description": "{api_key_id}", "schema": { "type": "string", "example": "241" } } ], "requestBody": { "description": "No request body required. Send an empty body." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "array", "items": { "type": "object", "properties": { "module_id": { "type": "integer", "description": "Unique numeric identifier for the module. Use as the `module` field in add/edit requests.", "example": 1 }, "pretty_name": { "type": "string", "description": "Full display name including profile type category", "example": "Malware > Respond to Malicious Causality Chains" }, "title": { "type": "string", "description": "Short title of the module.", "example": "Respond to Malicious Causality Chains" }, "label": { "type": "string", "description": "Label describing what the exception allow-lists (for example, \"Files / Folders in Allow List\").", "example": "Allow List of Remote Ipv4/ipv6 Ip Address, Range or Cidr" }, "profile_type": { "type": "string", "description": "Category of the protection profile this module belongs to.", "example": "Malware" }, "platforms": { "type": "array", "description": "List of platforms this module supports. Only use these platforms in add/edit requests for this module.", "items": { "type": "string", "example": "Windows" } }, "conditions_definition": { "type": "object", "description": "Schema definition for the `conditions` object required when creating or editing a legacy exception rule for this module. Each key is a condition field name, and its value describes the expected schema and a human-readable description.", "properties": { "remoteIpsWhitelist": { "type": "object", "properties": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "items": { "type": "object", "properties": { "type": { "type": "string" } } }, "minItems": { "type": "integer" } } }, "description": { "type": "string", "description": "Human-readable description of the condition field." } } } } } } } } } }, "examples": { "Example 1": { "value": { "reply": [ { "module_id": 1, "pretty_name": "Malware > Respond to Malicious Causality Chains", "title": "Respond to Malicious Causality Chains", "label": "Allow List of Remote Ipv4/ipv6 Ip Address, Range or Cidr", "profile_type": "Malware", "platforms": [ "Windows", "macOS" ], "conditions_definition": { "remoteIpsWhitelist": { "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": "List of valid Ipv4/ipv6 Ip Address, Ranges or Cidrs" } } } ] } } } } } } } } }, "/public_api/v1/legacy_exceptions/fetch": { "post": { "summary": "Fetch Legacy Exception Rules", "operationId": "get_legacy_exceptions", "tags": [ "Endpoint Management" ], "description": "Retrieves a paginated list of Legacy Exception rules for agents based on optional filters and sorting criteria.\n\nThis endpoint allows you to:\n- Retrieve all rules or filter by specific criteria\n- Sort results by any field in ascending or descending order\n- Paginate through large result sets\n- Get total count and filtered count of rules\n", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "{api_key}", "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " } }, { "name": "x-xdr-auth-id", "in": "header", "required": true, "description": "{api_key_id}", "schema": { "type": "string", "example": "241" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLegacyExceptionDataRequest" }, "examples": { "Example 1": { "value": { "request_data": { "search_from": 0, "search_to": 10, "sort": { "field": "id", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "ENABLED" }, { "field": "module", "operator": "in", "value": 43 }, { "field": "platform", "operator": "eq", "value": "Windows" } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPublicLegacyExceptionResponse" }, "examples": { "Example 1": { "value": { "reply": { "DATA": [ { "id": "d9c06bfa3f9b45a7a0196244e68d181d", "rule_name": "Legacy Exception Rule 1", "platform": "Linux", "conditions": "Process Name = Another test process AND Modules = Disable Injection OR Process Name = Test process AND Modules = Child Process Protection", "module": 43, "module_name": "Exceptions > Process Exceptions", "description": "rule 1", "generating_alert_id": null, "created_by": "John Doe", "modification_time": 1772111647000, "user_email": "john.doe@example.com", "status": "ENABLED", "profile_ids": [ 27 ], "associated_targets": [ "Any" ], "is_in_user_scope": true }, { "id": "0a2661779a2d4a87b051158ea47f0022", "rule_name": "Legacy Exception Rule 2", "platform": "Windows", "conditions": "Remote IP Address : 192.168.1.45", "module": 1, "module_name": "Malware > Respond to Malicious Causality Chains", "description": "test", "generating_alert_id": null, "created_by": "Jane Doe", "modification_time": 1772089294000, "user_email": "jane.doe@example.com", "status": "ENABLED", "profile_ids": [ 29 ], "associated_targets": [], "is_in_user_scope": true } ], "FILTER_COUNT": 2, "TOTAL_COUNT": 2 } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "HTTP error code." }, "err_msg": { "type": "string", "description": "High-level error message" }, "err_extra": { "type": "string", "description": "Detailed error information describing the specific validation failures." } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "invalid request - operator contains is unsupported for rule_name, conditions is not supported for filtering, module_name is not supported for filtering, description is not supported for filtering, value Enabled is not valid for field status, modification_time is not supported for filtering, profiles is not supported for filtering, generating_alert_id is not supported for filtering" } } } } } } } } } }, "/public_api/v1/legacy_exceptions/add": { "post": { "summary": "Add Legacy Exception Rule", "operationId": "add_legacy_exception", "tags": [ "Endpoint Management" ], "description": "Create a new legacy exception rule.\n\n**Prerequisites:**\n- Use [Get Legacy Exceptions Modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) API to find available `module` IDs, supported `platforms`, and the required `conditions` structure.\n- Use [Get endpoint security profiles](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-endpoints-get_profiles) API to find existing profile IDs to pass as `profile_ids`.\n- New profiles can be created via `/public_api/v1/profiles/prevention/add`.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "{api_key}", "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " } }, { "name": "x-xdr-auth-id", "in": "header", "required": true, "description": "{api_key_id}", "schema": { "type": "string", "example": "241" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/AddLegacyExceptionDataRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "name": "Test Legacy Exception rule 1", "platform": "Windows", "module": 1, "profile_ids": [ 29 ], "status": "ENABLED", "scope": "PROFILE", "description": "my legacy rule desc", "conditions": { "remoteIpsWhitelist": [ "192.168.1.45" ] } } } }, "Example 2": { "value": { "request_data": { "name": "Test kpep legacy rule", "platform": "macOS", "module": 43, "profile_ids": [ 53 ], "status": "ENABLED", "scope": "PROFILE", "description": "my legacy desc rule 2", "conditions": { "process_exceptions": [ { "processName": "test\\test.exe", "modules": [ { "moduleId": 141, "moduleName": "Kernel Privilege Escalation Protection" } ] } ] } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string", "description": "The ID of the newly created legacy exception rule.", "example": "f87c6f24205249d896677ab63626d4f4" } } }, "examples": { "Example 1": { "value": { "reply": "f87c6f24205249d896677ab63626d4f4" } } } } } } } } }, "/public_api/v1/legacy_exceptions/edit": { "post": { "summary": "Edit Legacy Exception Rule", "operationId": "edit_legacy_exception", "tags": [ "Endpoint Management" ], "description": "Update an existing legacy exception rule.\n\n**Prerequisites:**\n\nTo get the required fields:\n- Use [Get Legacy Exceptions Modules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-get_modules) API to retrieve existing exception details.\n- The `id` field in the fetch API response corresponds to `exception_id` in this request.\n- The `rule_name` field in the fetch API response corresponds to `name` in this request.\n- The `scope` field is not returned by the fetch API. Use `\"PROFILE\"` if `profile_ids` is non-empty in the fetch response; use `\"GLOBAL\"` if `profile_ids` is `[]`.\n", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "{api_key}", "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " } }, { "name": "x-xdr-auth-id", "in": "header", "required": true, "description": "{api_key_id}", "schema": { "type": "string", "example": "241" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/EditLegacyExceptionDataRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "exception_id": "f87c6f24205249d896677ab63626d4f4", "update_data": { "name": "Edit legacy exception rule", "platform": "Windows", "module": 1, "profile_ids": [ 29 ], "status": "DISABLED", "scope": "PROFILE", "description": "my legacy desc", "conditions": { "remoteIpsWhitelist": [ "192.168.1.45", "10.0.0.10-10.0.0.20" ] } } } } }, "Example 2": { "value": { "request_data": { "exception_id": "d9c06bfa3f9b45a7a0196244e68d181d", "update_data": { "name": "Edit legacy exception rule 1", "platform": "Linux", "module": 43, "profile_ids": [ 26 ], "status": "ENABLED", "scope": "PROFILE", "description": "test 3", "conditions": { "process_exceptions": [ { "processName": "Test process 1", "modules": [ { "moduleId": 67, "moduleName": "Disable Injection" } ] }, { "processName": "Test process 2", "modules": [ { "moduleId": 63, "moduleName": "Child Process Protection" } ] }, { "processName": "Test process 3", "modules": [ { "moduleId": 65, "moduleName": "Brute Force Protection" } ] } ] } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string", "description": "The ID of the edited legacy exception rule.", "example": "f87c6f24205249d896677ab63626d4f4" } } }, "examples": { "Example 1": { "value": { "reply": "f87c6f24205249d896677ab63626d4f4" } } } } } } } } }, "/public_api/v1/legacy_exceptions/delete": { "post": { "summary": "Delete Legacy Exception Rules", "operationId": "delete_legacy_exceptions", "tags": [ "Endpoint Management" ], "description": "Deletes one or more legacy exception rules by their IDs.\n\nUse [fetch](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-fetch) endpoint to retrieve the `id` values of the exceptions you want to delete.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "{api_key}", "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " } }, { "name": "x-xdr-auth-id", "in": "header", "required": true, "description": "{api_key_id}", "schema": { "type": "string", "example": "241" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "required": [ "exception_ids" ], "properties": { "exception_ids": { "type": "array", "description": "List of legacy exception IDs to delete. Corresponds to the `id` field returned by the [Fetch Legacy Exception Rules](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-legacy_exceptions-fetch) API.", "minItems": 1, "items": { "type": "string", "example": "f87c6f24205249d896677ab63626d4f4" } } } } } }, "examples": { "Example 1": { "value": { "request_data": { "exception_ids": [ "f87c6f24205249d896677ab63626d4f4" ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "integer", "description": "The number of successfully deleted legacy exception rules.", "example": 1 } } }, "examples": { "Example 1": { "value": { "reply": 1 } } } } } } } } }, "/public_api/v1/disable_injection_prevention_rules/fetch": { "post": { "summary": "Get Disable Injection and Prevention rules", "description": "Retrieves a paginated list of Disable Injection and Prevention rules based on optional filters and sorting criteria.\n\nThis endpoint allows you to:\n- Retrieve all rules or filter by specific criteria\n- Sort results by any field in ascending or descending order\n- Paginate through large result sets\n- Get total count and filtered count of rules\n", "operationId": "fetchDisableInjectionPreventionRules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": {} } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/GetInjectionDataRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "search_from": 0, "search_to": 1, "sort": { "field": "rule_id", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "active" } ] } } }, "Example 2": { "value": { "request_data": { "search_from": 0, "search_to": 10, "filters": [ { "field": "rule_name", "operator": "eq", "value": "Protect Critical app" }, { "field": "status", "operator": "eq", "value": "active" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicGetInjectionDataResponse" }, "examples": { "Example 1": { "value": { "reply": { "data": [ { "rule_id": "24bd70bab9d94905aa18773de2555969", "rule_name": "Protect Critical App", "description": "Disable injection prevention for critical business application", "platform": "windows", "status": "active", "expiration_time": 1770445053461, "process_name": "criticalApp.exe", "path": "string", "created_by": "John Doe", "creation_time": 1770358653000, "is_global": false, "profile_ids": [ 96 ] } ], "filter_count": 1, "total_count": 6 } } }, "Example 2": { "value": { "reply": { "data": [ { "rule_id": "24bd70bab9d94905aa18773de2555969", "rule_name": "Protect Critical App", "description": "Disable injection prevention for critical business application", "platform": "windows", "status": "active", "expiration_time": 1770445053461, "process_name": "criticalApp.exe", "path": "string", "created_by": "Public API - 241", "creation_time": 1770358653000, "is_global": true, "profile_ids": null } ], "filter_count": 1, "total_count": 6 } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "search_from: Input should be greater than or equal to 0" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "search_from: Input should be greater than or equal to 0" } } }, "Example 2": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "search_from: Input should be greater than or equal to 0" } } }, "Example 3": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Unknown field 'scope'" } } }, "Example 4": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Unsupported operator 'lte' for field rule_id" } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_injection_prevention_rules/add": { "post": { "summary": "Add Disable Injection and Prevention rule", "description": "Creates a new Disable Injection and Prevention rule to allow specific processes to bypass injection prevention.\n\nThis endpoint allows you to:\n- Define a new rule with a unique name and description\n- Specify the target platform (Windows, Linux, or macOS)\n- Set the process name and path to be protected\n- Configure expiration time\n- Apply the rule globally or to specific profiles\n", "operationId": "addDisableInjectionPreventionRule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": {} } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisableInjectionAddRulePAPIRequest" } } }, "examples": { "Profile rule for Windows": { "value": { "request_data": { "rule_name": "Global Windows Exception", "description": "Allow injection for trusted Windows application across all endpoints", "platform": "windows", "process_name": "trustedapp.exe", "path": "C:\\Program Files\\TrustedApp\\trustedapp.exe", "hours_to_expiration": 24, "profile_ids": [ 96 ], "scope": "profile" } } }, "Global rule for windows": { "value": { "request_data": { "rule_name": "Global Windows Exception", "description": "Allow injection for trusted Windows application across all endpoints", "platform": "windows", "process_name": "trustedapp.exe", "path": "C:\\Program Files\\TrustedApp\\trustedapp.exe", "hours_to_expiration": 24, "profile_ids": [], "scope": "global" } } }, "Profile rule for Linux": { "value": { "request_data": { "rule_name": "Development Server Exception", "description": "Temporary exception for development servers", "platform": "linux", "process_name": "node", "path": "/usr/bin/node", "hours_to_expiration": 24, "scope": "profile", "profile_ids": [ 201, 202 ] } } }, "Global rule for macos": { "value": { "request_data": { "rule_name": "macOS Design Tool", "description": "Exception for design application on macOS", "platform": "macos", "process_name": "DesignApp", "path": "/Applications/DesignApp.app/Contents/MacOS/DesignApp", "hours_to_expiration": 48, "scope": "global", "profile_ids": null } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InjectionResponseString" }, "examples": { "Example 1": { "value": { "reply": "e35dcf2150b74d19ba354fbe871f978d" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "hours_to_expiration: Value error, Invalid value '12'. Allowed values: {24, 48}" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "hours_to_expiration: Value error, Invalid value '12'. Allowed values: {24, 48}" } } }, "Example 2": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "The following profile ID(s) have a wrong type: [96]. The allowed types are: ['Exceptions']" } } }, "Example 3": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Value error, profile_ids are required when scope is 'profile'" } } }, "Example 4": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Value error, profile_ids can only be set when scope is 'profile'" } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP" }, "in": "header", "name": "Authorization", "required": true, "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "required": true, "description": "{api_key_id}" } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_injection_prevention_rules/disable": { "post": { "summary": "Disable Disable Injection and Prevention Rules", "description": "Disables one or more existing Disable Injection and Prevention rules by their IDs.\n\nThis endpoint allows you to:\n- Disable multiple rules in a single request\n- Immediately stop rules from being applied \n", "operationId": "disableDisableInjectionPreventionRules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": {} } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisableInjectionDisableRulesPAPIRequest" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableInjectionResponseString" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 404, "err_msg": "Requested resource not found while processing XDR public API", "err_extra": "Could not find Disable Injection and Prevention Rule(s) with the following ID(s): ['9133403bfc764080ad8909a6e05b67']" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 404, "err_msg": "Requested resource not found while processing XDR public API", "err_extra": "Could not find Disable Injection and Prevention Rule(s) with the following ID(s): ['9133403bfc764080ad8909a6e05b67']" } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP" }, "in": "header", "required": true, "name": "Authorization", "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_prevention/fetch": { "post": { "summary": "Get Disable Prevention Rules", "description": "Returns a list of Disable Prevention rules based on filters, sorting, and pagination.", "operationId": "fetchDisablePreventionRules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "search_from": 0, "search_to": 8, "sort": { "field": "rule_id", "keyword": "asc" }, "filters": [ { "field": "status", "operator": "eq", "value": "enabled" } ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/GetDataRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "search_from": 0, "search_to": 100, "sort": { "field": "rule_id", "keyword": "asc" }, "filters": [ { "field": "rule_id", "operator": "eq", "value": "1bce99ee792e4f0682d7c9bde0aaf44e" } ] } } }, "Example 2": { "value": { "request_data": { "search_from": 0, "search_to": 3, "sort": { "field": "modification_time", "keyword": "desc" }, "filters": [ { "field": "status", "operator": "eq", "value": "enabled" }, { "field": "modification_time", "operator": "gte", "value": 1762870187000 } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicGetDataResponse" }, "examples": { "Example 1": { "value": { "reply": { "data": [ { "rule_id": "1bce99ee792e4f0682d7c9bde0aaf44e", "rule_name": "DPR", "description": "Prevention rules using API", "platform": "linux", "conditions": { "hash": "3b7d28f7a6c1e9b0f4a5c2d9e8f1a0b6c7d4e5f8091a2b3c4d5e6f7a8b9c0d1 ", "path": "/*", "signer": "trusted company.inc", "command": "command line argument", "sign_thumbprint": "certificate thumbprint" }, "module_ids": [ 56 ], "profile_ids": [ 96 ], "scope": "profile", "status": "enabled", "created_by": "Jane Doe", "user_email": "jane.doe@example.com", "modification_time": 1764475578200, "associated_targets": [ "endpoint != AFDSFDS" ] } ], "filter_count": 1, "total_count": 4 } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_prevention/get_modules": { "post": { "summary": "Get Disable Prevention Modules", "description": "Returns a list of available modules for a specific platform.", "operationId": "getDisablePreventionModules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "platform": "windows" } } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisablePreventionGetModulesPAPIRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "platform": "windows" } } }, "Example 2": { "value": { "request_data": { "platform": "macos" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseArrayModules" }, "examples": { "Example 1": { "value": { "reply": [ { "module_id": 1, "name": "DLL Security", "description": "Memory Corruption Exploit", "profile_type": "Exploit", "conditions_definition": { "properties": { "hash": { "type": "string", "description": "Hash" }, "path": { "type": "string", "description": "Files / Folders", "minLength": 1 }, "command": { "type": "string", "description": "Command Line", "minLength": 1 }, "signer": { "type": "string", "description": "Signer Name", "minLength": 1 }, "sign_thumbprint": { "type": "string", "description": "Certificate Thumbprint", "minLength": 1 } } }, "additionalProperties": false, "minProperties": 1 } ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " }, "in": "header", "name": "Authorization", "required": true, "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_prevention/add": { "post": { "summary": "Add Disable Prevention Rule", "description": "Creates a new Disable Prevention rule.", "operationId": "addDisablePreventionRule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "rule_ids": [ "5bfb2a15ca2a4525a4e69f11792dfe61" ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisablePreventionAddRulePAPIRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "rule_name": "My MacOS Rule", "description": "Data prevention rule for MacOS", "platform": "macos", "module_ids": [ 38 ], "conditions": { "hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "path": "/usr/", "signer": "Trusted Company Inc.", "command": "command line argument" }, "profile_ids": [ 96 ], "status": "enabled", "scope": "profile" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseString" }, "examples": { "Example 1": { "value": { "reply": "330fc8dec96a4810af886af328e73264" } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_prevention/edit": { "post": { "summary": "Edit Disable Prevention Rule", "description": "Updates an existing Disable Prevention rule.", "operationId": "editDisablePreventionRule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "rule_ids": [ "5bfb2a15ca2a4525a4e69f11792dfe61" ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisablePreventionEditRulePAPIRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "rule_name": "My MacOS Rule", "description": "Data prevention rule for MacOS", "platform": "macos", "module_ids": [ 38 ], "conditions": { "hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "path": "/usr/", "signer": "Trusted Company Inc.", "command": "command line argument" }, "profile_ids": [ 96 ], "status": "enabled", "scope": "profile", "rule_id": "5bfb2a15ca2a4525a4e69f11792dfe61" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseString" }, "examples": { "Example 1": { "value": { "reply": "330fc8dec96a4810af886af328e73264" } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " }, "in": "header", "name": "Authorization", "required": true, "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/disable_prevention/delete": { "post": { "summary": "Delete Disable Prevention Rules", "description": "Deletes one or more Disable Prevention rules based on the provided rule ID.", "operationId": "deleteDisablePreventionRules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "rule_ids": [ "5bfb2a15ca2a4525a4e69f11792dfe61" ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "$ref": "#/components/schemas/DisablePreventionDeleteRulesPAPIRequest" } } }, "examples": { "Example 1": { "value": { "request_data": { "rule_ids": [ "00e2308ad4a54fca8b478766ee9de57e" ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponseString" } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP " }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string", "example": "241" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/get_versions": { "post": { "operationId": "postGetVersions", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get Distribution version", "description": "Get a list of all the agent versions to use for creating a distribution list.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": {} } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "windows": [ "", "", "", "" ], "linux": [ "", "", "", "" ], "macos": [ "", "", "" ] } } }, "properties": { "reply": { "type": "object", "properties": { "windows": { "type": "array", "description": "List of Windows agent versions.", "items": { "type": "string" } }, "linux": { "type": "array", "description": "List of Linux agent versions.", "items": { "type": "string" } }, "macos": { "type": "array", "description": "List of Mac agent versions.", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/create": { "post": { "operationId": "postCreate", "summary": "Create distributions", "description": "Create an installation package. This is an async call that returns the distribution ID; it does not mean that the creation succeeded. To confirm the package has been created, check the status of the distribution by running the [Get Distribution Status](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-distributions-get_status) API.\r\n\r\n>Required license: \r\n>\r\n>**Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "name": "", "platform": "windows", "package_type": "standalone", "agent_version": "" } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "name", "package_type", "agent_version", "deployment_platform", "default_namespace", "run_on_master_node", "run_on_all_nodes" ], "properties": { "name": { "type": "string", "description": "The name of the installation package." }, "platform": { "type": "string", "description": "The installation platform.", "enum": [ "windows", "linux", "macos", "android" ] }, "package_type": { "type": "string", "description": "A string representing the type of package to create. Each JSON object must contain *one* of the following keywords:\n- `standalone`: Installation for a new agent. When using this, you must include the `platform` field with one of the following values: `windows`, `linux`, `macos`, `android`, `kubernetes`, `helm`.\n- `upgrade`: Upgrade of an agent from ESM. When using this, you must include the `agent_version` field with one of the following values: `windows_version`, `linux_version`, or `macos_version`.\n- `caas_embedded`: Container-embedded XDR agent installation using the CaaS Generic Installer (Linux dockerfile-based deployment)." }, "agent_version": { "type": "string", "description": "Use `agent_version` when creating a standalone installer. The value should be the agent version number.\n" }, "windows_version": { "type": "string", "description": "Use `windows_version` when creating an upgrade package. The value is the relevant version number." }, "linux_version": { "type": "string", "description": "Use `linux_version` when creating an upgrade package. The value is the relevant version number." }, "macos_version": { "type": "string", "description": "Use `macos_version` when creating an upgrade package. The value is the relevant version number." }, "deployment_platform": { "type": "string", "description": "When the `package_type` is `kubernetes` or `helm`, use the `deployment_platform` to indicate the type of platform. Valid values include:\n- `standard`\n- `openshift`\n- `gcos`\n- `bottlerocket`\n- `gke_autopilot`" }, "default_namespace": { "type": "string", "description": "The default namespace" }, "node_selector": { "type": "object", "description": "The node selector in the following format:\n`\"node_selector\": {\"key\": \"val\"}'", "additionalProperties": {} }, "proxy": { "type": "array", "items": { "type": "string" } }, "cluster_name": { "type": "string", "description": "Cluster name" }, "run_on_master_node": { "type": "boolean", "description": "Whether or not to run on the master node." }, "run_on_all_nodes": { "type": "boolean", "description": "Whether or not to run on all nodes." } } } } }, "examples": { "New Installation example": { "value": { "request_data": { "name": "", "platform": "windows", "package_type": "standalone", "agent_version": "windows_version" } } }, "Upgrade example": { "value": { "request_data": { "name": "", "package_type": "upgrade", "agent_version": "windows_version" } } }, "Kubernetes distribution": { "value": { "request_data": { "name": "PAPI Dist K8s", "description": "Created using PAPI", "endpoint_tags": [ "new-tag" ], "package_type": "kubernetes", "platform": "linux", "agent_version": "8.8.0.10594", "deployment_platform": "standard", "default_namespace": "cortex-xdr", "node_selector": { "key": "val" }, "proxy": [ "10.10.10.1:8080" ], "cluster_name": "some_name", "run_on_master_node": true, "run_on_all_nodes": false } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "distribution_id": "" } } }, "properties": { "reply": { "type": "object", "properties": { "distribution_id": { "type": "string", "description": "Installation package ID." } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/get_status": { "post": { "operationId": "postGetStatus", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get Distribution status", "description": "Check the status of the installation package.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "distribution_id": "" } } }, "properties": { "request_data": { "type": "object", "required": [ "distribution_id" ], "properties": { "distribution_id": { "type": "string", "description": "The installation package ID." } } } }, "required": [ "request_data" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "status": "Completed" } } }, "properties": { "reply": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the installation package." } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/get_dist_url": { "post": { "operationId": "postGetDistUrl", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get Distribution URL", "description": "Get the distribution URL for downloading the installation package.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "distribution_id": "", "package_type": "x86" } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "distribution_id", "package_type" ], "properties": { "distribution_id": { "type": "string", "description": "Installation package ID." }, "package_type": { "type": "string", "description": "A string representing the type of installation package. Select *one* of the following valid keywords and values:\n- `upgrade`\nPackage type should match the distribution type or platform:\n- `sh`: x86_64 Linux SH installer\n- `rpm`: x86_64 Linux RPM installer\n- `deb`: x86_64 Linux DEB installer\n- `aarch64_sh`: aarch64 Linux SH installer\n- `aarch64_rpm`: aarch64 Linux RPM installer\n- `aarch64_deb`: aarch64 Linux DEB installer\n- `pkg`: Mac\n- `x86`: Windows\n- `x64`: Windows\n- `arm`: Windows ARM64" } } } } }, "examples": { "example-1": { "value": { "request_data": { "distribution_id": "", "package_type": "x86" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "distribution_url": "" } } }, "properties": { "reply": { "type": "object", "properties": { "distribution_url": { "type": "string", "description": "URL for downloading the installation package." } } } } }, "examples": { "example-1": { "value": { "reply": { "distribution_url": "" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/get_distributions": { "post": { "summary": "Get Distributions", "description": "Retrieves a paginated list of existing agent installations and metadata based on optional filters and sorting criteria.\n\nThis endpoint allows you to:\n\n- Retrieve existing agent installations or filter by specific criteria\n- Paginate through large result sets\n- Sort results by any field in ascending or descending order\n- Get total count and filtered count of agent installations\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**\n", "operationId": "get_distributions", "tags": [ "Endpoint Management" ], "requestBody": { "required": true, "description": "Request body containing pagination, sorting, and filtering criteria for agent distributions", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "search_from": 0, "search_to": 5, "sort": { "field": "distribution_id", "keyword": "asc" }, "filters": [ { "field": "distribution_id", "operator": "eq", "value": "068bcaad02974ac5b223bfa786e7573c" }, { "field": "name", "operator": "contains", "value": "macos-369121" }, { "field": "description", "operator": "contains", "value": "macos-369121" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "platform", "operator": "eq", "value": "macos" }, { "field": "agent_version", "operator": "contains", "value": "9.1." }, { "field": "status", "operator": "eq", "value": "completed" } ] } } }, "properties": { "request_data": { "$ref": "#/components/schemas/GetDistributionDataRequest" } } }, "examples": { "Sorting and all filter options": { "value": { "request_data": { "search_from": 0, "search_to": 5, "sort": { "field": "distribution_id", "keyword": "asc" }, "filters": [ { "field": "distribution_id", "operator": "eq", "value": "068bcaad02974ac5b223bfa786e7573c" }, { "field": "name", "operator": "contains", "value": "macos-369121" }, { "field": "description", "operator": "contains", "value": "Production-ready macos agent installer with enhanced monitoring capabilities" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "platform", "operator": "eq", "value": "macos" }, { "field": "agent_version", "operator": "contains", "value": "9.1." }, { "field": "status", "operator": "eq", "value": "completed" } ] } } } } } } }, "responses": { "200": { "description": "Successful response containing the list of distributions matching the criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDistributionDataResponse" }, "examples": { "Example 1": { "value": { "reply": { "data": [ { "distribution_id": "068bcaad02974ac5b223bfa786e7573c", "name": "macos-369121", "description": "Production-ready macos agent installer with enhanced monitoring capabilities", "package_type": "standalone", "platform": "macos", "agent_version": "9.1.0.9877", "status": "completed", "tags": [ "production", "stable" ], "eol_time": 1735689600, "created_by": "John Doe", "creation_time": 1704067200, "modification_time": 1704153600, "supported_packages": [ "pkg" ] } ], "filter_count": 1, "total_count": 10 } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or malformed JSON", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "search_from: Input should be greater than or equal to 0" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "summary": "Invalid pagination parameters", "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Unsupported operator 'contains' for field platform" } } }, "Example 2": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API.", "err_extra": "Search size must fulfill the requirement: 0 < search_size <= 100" } } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An unexpected error occurred by XDR public API", "err_extra": "Invalid value 'serverless_functions' for field platform" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "summary": "Internal server error", "value": { "reply": { "err_code": 500, "err_msg": "An unexpected error occurred by XDR public API", "err_extra": "Invalid value 'serverless_functions' for field platform" } } }, "Example 2": { "value": { "reply": { "err_code": 500, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Invalid parameter names: creation_time" } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP" }, "in": "header", "required": true, "name": "Authorization", "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ] } }, "/public_api/v1/distributions/delete": { "post": { "summary": "Delete agent installation packages", "tags": [ "Endpoint Management" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": true } }, "properties": { "reply": { "type": "boolean", "description": "Whether the deletion was successful." } } }, "examples": { "Example 1": { "value": { "reply": true } } } } } } }, "operationId": "post-public_api-v1-distributions-delete", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "distribution_id": "1223" } } }, "properties": { "request_data": { "type": "object", "properties": { "distribution_id": { "type": "string", "description": "Installation package distribution ID." } } } } }, "examples": { "Example 1": { "value": { "request_data": { "distribution_id": "36ffe3f7ab7c4e7188e27d633ea72c3d" } } } } } } }, "description": "Delete an agent installation package. The distribution ID is required and can be found in the [Create distributions](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/endpoint-management#post-public_api-v1-distributions-create) API response or in the **Agent Installations** screen in the Cortex Console.\n\n> **Note:**\n> Once you delete an installation package, it prevents new agents using the package, including VDI, from registering. \n\n>**Required license:** \n>\n>Cortex XDR Prevent or Cortex XDR Pro per Endpoint" } }, "/public_api/v1/device_control/get_violations": { "post": { "operationId": "postGetViolations", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Get Violations", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "type", "operator": "in", "value": [ "disk drivE" ] } ], "search_to": 1 } } }, "properties": { "request_data": { "type": "object", "description": "An empty object returns all results.", "properties": { "filters": { "type": "array", "description": "Provides an array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies the violation field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `type`: Type of violation.\n- `timestamp`: Timestamp of the violation.\n- `ip_list`: List of IP addresses.\n- `vendor`: Name of vendor.\n- `vendor_id`: Vendor ID.\n- `product`: Name of product.\n- `product_id`: Product ID.\n- `serial`: Serial number.\n- `hostname`: Hostname.\n- `violation_id_list`: List of violation IDs.\n- `username`: Username.", "enum": [ "endpoint_id_list", "type", "timestamp", "ip_list", "vendor", "vendor_id", "product", "product_id", "serial", "hostname", "violation_id_list", "username" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords are:\n`in`\n— Permitted for all fields except `timestamp`.\n`gte` / `lte`\n— Permitted only for `timestamp`.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "integer", "string" ], "description": "Value that this filter must match. The contents of this field will differ depending on the violation field that you specified for this filter:\n- `timestamp`: Integer, in UTC timezone epoch milliseconds\n- `violation_id_list`: List of integers\n- `ip_list`: Must contain an IP string\n- `type`: Must be either `cd-rom`, `disk drive`, `floppy disk`, `portable device`\n- All other fields need to be list of strings.", "items": { "type": [ "integer", "string" ] } } }, "required": [ "field", "operator", "value" ] } }, "search_from": { "type": "integer", "description": "Integer representing the starting offset within the query result set from which you want violations returned.\nViolations are returned as a zero-based list. Any violation indexed less than this value is not returned in the final result set and defaults to zero." }, "search_to": { "type": "integer", "description": "An integer representing the end of offset within the result set after which you do not want violations returned.\nViolations in the violation list that are indexed higher than this value are not returned in the final results set. Defaults to zero, which returns all alerts to the end of the list." }, "sort": { "type": "object", "description": "Identifies the sort order for the result set.", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "type", "timestamp", "ip_list", "vendor", "vendor_id", "product", "product_id", "serial", "hostname", "violation_id_list", "username" ], "description": "The field you want to sort by." }, "value": { "type": "string", "description": "Can be either `asc` (ascending) or `desc` (descending).", "enum": [ "asc", "desc" ], "default": "desc" } }, "required": [ "field", "value" ] } } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "type", "operator": "in", "value": [ "disk drive" ] } ], "search_to": 1 } } } } } }, "description": "You can send a request to retrieve either *all* or *filtered* results." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "total_count": 10, "result_count": 1, "violations": [ { "hostname": "", "username": "test", "ip": "", "timestamp": 1576260019000, "violation_id": 11, "type": "Disk Drive", "vendor_id": "", "vendor": "", "product_id": "", "product": "", "serial": "", "endpoint_id": "" } ] } } }, "properties": { "reply": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of total results of this filter without paging." }, "result_count": { "type": "integer", "description": "Number of alerts actually returned as a result." }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/violation" } } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "description": "Gets a list of device control violations filtered by selected fields. You can retrieve up to 100 violations.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 100.\n- Offset is the zero-based number of incidents from the start of the result set.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "tags": [ "Endpoint Management" ] } }, "/public_api/v1/tags/agents/assign": { "post": { "operationId": "postAssign", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Assign Tags", "description": "Assign one or more tags to one or more endpoints.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } }, "properties": { "request_data": { "type": "object", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `last_seen`: When an endpoint was last seen.\n- `first_seen`: When an endpoint was first seen.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `hostname`: Hostname.\n- `isolate`: If the endpoint was isolated.\n- `username`: Name of user.\n- `scan_status`: Status of the scan.\n- `group_name`: Group name the agent belongs to.\n- `endpoint_status`: Status of the endpoint ID.\n- `operational_status`: Operational status.\n- `public_ip_list`: List of public IP addresses.", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "ip_list", "group_name", "platform", "alias", "isolate", "hostname" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `operational_status`: List of strings.\n- `endpoint_status`: Permitted values are `connected`, `lost`, `disconnected`, `uninstalled`.\n- `ip_list`, `public_ip_list`: List of strings, for example \"192.168.5.12\".\n- `platform`: Permitted values are `windows`, `linux`, `macos`, `android`, `ios`.\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n- `operational_status`: Permitted values are `protected`, `partially_protected`, `unprotected`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "string", "integer" ], "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `operational_status`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected`, `disconnected`, `lost`, or `uninstalled`.\n- `operational_status`: Must contain only the following valid values: `protected`, `partially_protected`, `unprotected`.\n- `ip_list`, `public_ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, `android`, or `ios`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.\n- `scan_status`: Must contain only the following valid values: `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "tag": { "type": "string", "description": "The tag you want to assign." } } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "tag": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=The tag name was assigned successfully." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "x Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/tags/agents/create": { "post": { "operationId": "postCreateTag", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Create Tag", "description": "Create a new agent tag in the `endpoint_tags` family.\n\nThe tag name must be a string of no more than 64 characters and must not contain wildcard characters (for example, `*`). If a tag with the same name already exists, the request fails with a 409 error.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "tag": "my-tag" } } }, "properties": { "request_data": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 64, "description": "The name of the tag to create. Maximum 64 characters. Wildcard characters (for example, `*`) are not allowed." } }, "required": [ "tag" ] } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "tag": "my-tag" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "string", "description": "Confirmation message, for example: \"Successfully created a new tag - my-tag\"." } } } }, "400": { "description": "Bad Request. The tag is missing, not a string, exceeds 64 characters, or contains invalid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "409": { "description": "Conflict. A tag with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/tags/agents/remove": { "post": { "operationId": "postRemove", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "summary": "Remove Tags", "description": "Remove one or more tags from one or more endpoints.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the following API request fields.", "properties": { "filters": { "type": "array", "description": "Array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `endpoint_status`: Status of the endpoint ID.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `group_name`: Group name the agent belongs to.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `isolate`: If the endpoint was isolated.\n- `hostname`: Hostname", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "ip_list", "group_name", "platform", "alias", "isolate", "hostname" ] }, "operator": { "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings.\n- `endpoint_status`: Permitted values are `connected` or `disconnected`.\n- `ip_list`: List of strings, for example 192.168.5.12.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "string", "integer" ], "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `distribution_name`, `hostname`, `alias`, `group_name`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected` or `disconnected`\n- `ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "tag": { "type": "string", "description": "The tag you want to remove." } } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "tag": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=tag name removed successfully." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/endpoints/restore": { "post": { "operationId": "postRestore", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Restore File", "description": "Restore a quarantined file on a requested endpoints.\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 100.\n- Offset is the zero-based number of incidents from the start of the result set.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "file_hash": "", "incident_id": 302 } } }, "properties": { "request_data": { "type": "object", "required": [ "file_hash" ], "description": "A dictionary containing the API request fields.", "properties": { "file_hash": { "type": "string", "description": "String that represents the file in hash. Hash must be a valid SHA256." }, "endpoint_id": { "type": "string", "description": "Endpoint ID.\n\nNote: If you do not enter a specific endpoint ID, the request will run restore on all endpoints which relate to the quarantined file you defined." }, "incident_id": { "type": "integer", "description": "String representing the incident ID.\nWhen included in the request, the Restore File action will appear in the Cortex XDR Incident View Timeline tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "file_hash": "", "incident_id": 302 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": "673" } } }, "properties": { "reply": { "type": "object", "properties": { "action_id": { "type": "string" }, "endpoints_count": { "type": "string" } } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "status": 1, "endpoints_count": "673" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/actions/file_retrieval_details": { "post": { "operationId": "postFileRetrievalDetails", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "File Retrieval Details", "description": "View the API required to call in order to download the file retrieved by the [Retrieve File](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-endpoints-file_retrieval) API request according to the action ID.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**\n\nThe response contains a file hash you need to download and then unzip to view:\n1. Download the file.\n\n\n``` curl\ncurl -XPOST \"https://api-{fqdn}/public_api/v1/download/\" \n-H \"x-xdr-auth-id:{API_KEY_ID}\" \n-H \"Authorization:{API_KEY}\" \n-H 'Content-Type:application/json' \n--output /tmp/file.zip\n```\n2. Unzip the file: `unzip /tmp/file.zip`\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "group_action_id": "" } } }, "properties": { "request_data": { "type": "object", "required": [ "group_action_id" ], "description": "A dictionary containing the API request fields.", "properties": { "group_action_id": { "type": "string", "description": "The action ID of the [Retrieve File](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-endpoints-file_retrieval) API response." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "group_action_id": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "data": { "": "https://api-{fqdn}/public_api/v1/download/" } } } }, "properties": { "reply": { "type": "object", "properties": { "data": { "type": "object", "properties": { "endpoint_ID": { "type": "string", "description": "API required to call in order to download the retrieved result." } } } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "": "https://api-{fqdn}/public_api/v1/download/" } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/hash_exceptions/allowlist": { "post": { "operationId": "postAllowlist", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Allow List Files", "description": "Add files which do not exist in the allow or block lists to an allow list.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF29E5D553E4", "365296EB1B---FCF69E3D553E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF79E5D553D4" ], "comment": "test", "incident_id": 5 } } }, "properties": { "request_data": { "type": "object", "required": [ "hash_list" ], "description": "A dictionary containing the API request fields.", "properties": { "hash_list": { "type": "array", "description": "A list of hashed files you want to add to the allow list. Hash must be a valid SH256.", "items": { "type": "string" } }, "comment": { "type": "string", "description": "Additional information regarding the action." }, "incident_id": { "type": "integer", "description": "The incident ID related to the hash.\nWhen included in the request, the **Allow List** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF29E5D553E4", "365296EB1B---FCF69E3D553E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF79E5D553D4" ], "comment": "test", "incident_id": 5 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=File successfully added to the allow list." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/quarantine/status": { "post": { "operationId": "postStatus", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Get Quarantine Status", "description": "Retrieve the quarantine status for a specified files.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "files": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "" } ] } } }, "properties": { "request_data": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "description": "Array of endpoint IDs, filepaths, and file hash.", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID" }, "file_path": { "type": "string", "description": "File hash. Must be a valid SHA256." }, "file_hash": { "type": "string", "description": "File path." } } } } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "files": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "", "status": false } ] } }, "properties": { "reply": { "type": "array", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID." }, "file_path": { "type": "string", "description": "File path." }, "file_hash": { "type": "string", "description": "File hash." }, "status": { "type": "boolean", "description": "The file's status.\nTrue: The file is quarantined.\nFalse: The file is not quarantined." } } } } } }, "examples": { "example-1": { "value": { "reply": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "", "status": false } ] } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } }, "parameters": [] }, "/public_api/v1/endpoints/quarantine": { "post": { "operationId": "postQuarantine", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Quarantine Files", "description": "Quarantine file on selected endpoints. You can select up to 1000 endpoints.\n\nNote: A success response means that the request reached the defined endpoints, however if the file was not found there, no quarantine action will take place. To ensure if the file has been quarantined, check the Cortex XDR Action Center.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 1000.\n- Offset is the zero-based number of incidents from the start of the result set.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "file_path": "C:\\\\test_x64.msi", "file_hash": "" } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "filters", "file_path", "file_hash" ], "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.", "enum": [ "endpoint_id_list" ] }, "operator": { "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings", "enum": [ "in" ] }, "value": { "type": "array", "description": "Value that this filter must match. Valid keywords:\n- `endpoint_id_list`: Array of strings", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "file_path": { "type": "string", "description": "The path of the file you want to quarantine. You must enter a proper path and not symbolic links." }, "file_hash": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Quarentine File** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "file_path": "C:\\\\test_x64.msi", "file_hash": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "[ID value]", "status": "1", "endpoints_count": "673" } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": "ID of action to quarantine selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the file quarantine succeeded either:\n- In Cortex XDR console, navigate to **Response** > **Action Center** and search for the action ID. Make sure the **Action ID** field is selected in the table **Layout** settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-actions-get_action_status) API request." }, "status": { "type": "string", "description": "Integer representing whether the action:\n- `1`: succeeded\n- `0`: failed" }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "[ID value]", "status": "1", "endpoints_count": "673" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/hash_exceptions/blocklist": { "post": { "operationId": "postBlocklist", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Block List Files", "description": "Add files which do not exist in the allow or block lists to a block list. You can view the block list in the UI at **Incident Response** > **Action Center** > **Block List**.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF69E7D553E4", "365296EB1B---FCF69E5D523E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF63E5D553D4" ], "comment": "test", "incident_id": 5 } } }, "properties": { "request_data": { "type": "object", "required": [ "hash_list" ], "description": "A dictionary containing the API request fields.", "properties": { "hash_list": { "type": "array", "description": "A list of hashed files you want add to a block list. Hash must be a valid SH256.", "items": { "type": "string" } }, "comment": { "type": "string", "description": "Additional information regarding the action." }, "incident_id": { "type": "integer", "description": "The incident ID related to the hash.\nWhen included in the request, the **Block List** action appears in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF69E7D553E4", "365296EB1B---FCF69E5D523E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF63E5D553D4" ], "comment": "test", "incident_id": 5 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=File successfully added to block list." } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/endpoints/unisolate": { "post": { "operationId": "postUnisolate", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Unisolate Endpoints", "description": "Reverse the isolation of one or more endpoints in single request.\n\nNote: You can only send a request with either `endpoint_id` to unisolate one endpoint or with filters to unisolate more than one endpoint. An error is raised if you try to use both `endpoint_id` and the filters.\n\nRequired license: **Cortex XDR Prevent** or **Cortex XDR Pro per Endpoint**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "dist_name", "operator": "IN", "value": [ "MG" ] } ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "properties": { "filters": { "type": "array", "description": "An array of filter fields for unisolating a number of endpoints at once.\nNote: This field is only required if unisolating more than one endpoint.", "items": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.", "enum": [ "endpoint_id_list" ] }, "operator": { "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings", "enum": [ "IN" ] }, "value": { "type": "array", "description": "Value that this filter must match. Valid keywords:\n- `endpoint_id_list`: List of strings", "items": { "type": "string" } } } } }, "endpoint_id": { "type": "string", "description": "The ID of the endpoint to unisolate.\n\nNote: this field is only required if unisolating one endpoint." }, "incident_id": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Unisolate Endpoints** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } } }, "examples": { "Unisolate one endpoint": { "value": { "request_data": { "endpoint_id": "" } } }, "Unisolate more than one endpoint": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "IN", "value": [ "", "", "" ] } ] } } } } } }, "description": "One of `endpoint_id` of `filters` is required, but not both." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": "ID of the action to unisolate selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the endpoint was restored either:\n- In the Cortex XDR console, navigate to **Response** > **Action Center** > **Isolation** and search for the action ID. Make sure the **Action ID** field is selected in the table **Layout** settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/endpoints/abort_scan": { "post": { "operationId": "postAbortScan", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Cancel Scan Endpoints", "description": "Cancel the scan of selected endpoints. A scan can only be aborted if the selected endpoints are in **Pending** or in **Progress** status.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Offset is the zero-based number of endpoints from the start of the result set.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "filters" ], "properties": { "filters": { "type": [ "array", "string" ], "description": "An array of filter fields to filter which endpoints to cancel scanning.\nTo cancel scan of all endpoints, use the value \"all\".", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `dist_name`: Name of the distribution list.\n- `first_seen`: When an endpoint was first seen.\n- `last_seen`: When an endpoint was last seen.\n- `ip_list`: List of IP addresses.\n- `group_name`: Name of endpoint group.\n- `platform`: Type of operating system.\n- `alias`: Endpoint alias name.\n- `isolate`: If an endpoint has been isolated.\n- `hostname`: Name of host.\n- `username`: Name of user.", "enum": [ "endpoint_id_list", "dist_name", "first_seen", "last_seen", "ip_list", "group_name", "platform", "alias", "isolate", "hostname", "username", "scan_status" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings\n- `ip_list`: List of strings, for example 192.168.5.12\n- `platform`: Permitted values are `windows`, `linux`, `macos`, `android`\n- `isolate`: Permitted values are `isolated` or `unisolated`\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "integer", "array", "string" ], "description": "Value that this filter must match. Valid keywords:\n- `first_seen`, `last_seen`: Integer in timestamp epoch milliseconds, UTC timezone\n- `endpoint_id_list`, `dist_name`, `hostname`, `alias`, `group_name`: List of strings\n- `ip_list`: List of strings, for example 192.168.5.12\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "incident_id": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Cancel Scan Endpoints** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "To cancel scan of all endpoints": { "value": { "request_data": { "filters": "all" } } }, "To cancel scan of filtered endpoints": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": "ID of action to cancel scan selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the scan succeeded either:\n- In Cortex XDR console, navigate to **Response** > **Action Center** and search for the action ID. Make sure the **Action ID** field is selected in the table Layout settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/endpoints/scan": { "post": { "operationId": "postScan", "tags": [ "Response Action" ], "summary": "Scan Endpoints", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "filters" ], "properties": { "filters": { "type": "object", "description": "An array of filter fields. To scan all endpoints, use the value `all`.", "additionalProperties": { "type": "object", "required": [ "field", "operator", "value" ], "properties": { "field": { "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `dist_name`: Name of the distribution list.\n- `first_seen`: When an endpoint was first seen.\n- `last_seen`: When an endpoint was last seen.\n- `ip_list`: List of IP addresses.\n- `group_name`: Name of endpoint group.\n- `platform`: Type of operating system.\n- `alias`: Endpoint alias name.\n- `isolate`: If an endpoint has been isolated.\n- `hostname`: Name of host.", "enum": [ "endpoint_id_list", "dist_name", "first_seen", "last_seen", "ip_list", "group_name", "platform", "alias", "isolate", "hostname" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings\n- `ip_list`: List of strings, for example 192.168.5.12\n- `platform`: Permitted values are `windows`, `linux`, `macos`, `android`\n- `isolate`: Permitted values are `isolated` or `unisolated`\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.", "enum": [ "in", "gte", "lte" ] }, "value": { "type": [ "array", "string", "integer" ], "description": "Value that this filter must match. Valid keywords:\n- `first_seen`, `last_seen`: Integer representing the number of milliseconds after the Unix epoch, UTC timezone.\n- `endpoint_id_list`, `dist_name`, `hostname`, `alias`, `group_name`: List of strings\n- `ip_list`: Must contain an IP address string\n- `isolate`: Must be `isolated` or `unisolated`.\n- `platform`: Must be either `windows`, `linux`, `macos`, or `android`.", "items": { "type": "string" } } } } }, "incident_id": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Scan Endpoints** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } } }, "examples": { "Scan all endpoints": { "value": { "request_data": { "filters": "all" } } }, "Scan filtered endpoints": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test\"" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } } } }, "description": "Note: You can send a request to retrieve either **all** or **filtered** results." }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": "673" } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": "ID of action to scan selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the scan was successful either:\n- 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.\n- Send a [Get Action Status](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "description": "Run a scan on selected endpoints.\n- Response is concatenated using AND condition (OR is not supported).\n- Offset is the zero-based number of incidents from the start of the result set.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ] } }, "/public_api/v1/actions/get_action_status": { "post": { "operationId": "postGetActionStatus", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Response Action" ], "summary": "Get Action Status", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "group_action_id": "" } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "group_action_id" ], "properties": { "group_action_id": { "type": "integer", "description": "Action ID of the selected request." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "group_action_id": 123456789 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "data": { "": "COMPLETED_SUCCESSFULLY" } } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "data": { "type": "object", "properties": { "agent_id": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "CANCELLED", "PENDING_ABORT", "ABORTED", "EXPIRED", "COMPLETED_PARTIAL", "COMPLETED_SUCCESSFULLY", "FAILED", "TIMEOUT" ] } } } } } } }, "examples": { "example-1": { "value": { "reply": { "data": { "": "COMPLETED_SUCCESSFULLY" } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "description": "Retrieve the status of the requested actions according to the action ID.\n\nRequired license: **Cortex XDR Prevent**, **Cortex XDR Pro per Endpoint**, or **Cortex XDR Pro per GB**" } }, "/public_api/v1/scripts/run_snippet_code_script": { "post": { "operationId": "postRunSnippetCodeScript", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Script Execution" ], "summary": "Run Snippet Code Script", "description": "Initiate a new endpoint script execution action using provided snippet code. Cortex XDR supports sending your request in Base64.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "snippet_code": "print (\"7\")" } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "filters", "snippet_code" ], "properties": { "filters": { "type": "array", "description": "An array of filter fields for running the script on a number of endpoints at once.", "items": { "type": "object", "properties": { "field": { "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.", "enum": [ "endpoint_id_list" ] }, "operator": { "type": "string", "enum": [ "in" ], "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings" }, "value": { "type": "array", "description": "Value that this filter must match.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "timeout": { "type": "integer", "description": "The timeout in seconds for this execution. Default value is 600.", "default": 600 }, "snippet_code": { "type": "string", "description": "Section of a script you want to initiate on an endpoint." }, "incident_id": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Run Snippet Code Script** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "snippet_code": "print (\"7\")" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": 21 } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": " ID of the action initiated. ID will be used as a reference to track in the action center." }, "endpoints_count": { "type": "integer", "description": "Number of endpoints the action was initiated on." } } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "endpoints_count": 21 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/scripts/run_script": { "post": { "operationId": "postRunScript", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Script Execution" ], "summary": "Run Script", "description": "Initiate a new endpoint script execution action using a script from the script library. The script can be run on up to 1000 endpoints.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "script_uid": "", "parameters_values": { "x": "param input as returned in Get Script Metadata", "y": 4 } } } }, "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "required": [ "filters", "script_uid" ], "properties": { "filters": { "type": "array", "description": "Array of filter fields for running the script on a number of endpoints at once.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.", "enum": [ "endpoint_id_list" ] }, "operator": { "type": "string", "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings", "enum": [ "in" ], "default": "in" }, "value": { "type": "array", "description": "Value that this filter must match.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "script_uid": { "type": "string", "description": "GUID, unique identifier of the script, returned by the [Get Scripts](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/script-execution#post-public_api-v1-scripts-get_scripts) API per script." }, "parameters_values": { "type": "object", "description": "Dictionary containing the parameter name, `key`, and its value for this execution, `value`.\n\nYou can obtain these values by running [Get Script Metadata](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/script-execution#post-public_api-v1-scripts-get_script_metadata) API.", "properties": { "x": { "type": "string" }, "y": { "type": "integer" } }, "required": [ "x", "y" ] }, "timeout": { "type": "integer", "description": "Timeout in seconds for this execution. Default value is 600.", "default": 600 }, "incident_id": { "type": "string", "description": "Incident ID.\nWhen included in the request, the **Run Script** action will appear in the **Cortex XDR Incident View Timeline** tab." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "script_uid": "", "parameters_values": { "x": "param input as returned in Get Script Metadata", "y": 4 } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "action_id": 22519813685366, "status": 1, "endpoints_count": 1 } } }, "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "integer", "description": "ID of the action initiated. ID will be used as a reference to track in the action center." }, "endpoints_count": { "type": "integer", "description": "Number of endpoints the action was initiated on." }, "status": { "type": "integer", "description": "Integer representing whether the action:\n- `1`: succeeded\n- `0`: failed" } } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": 22519813685366, "status": 1, "endpoints_count": 1 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } } } }, "/public_api/v1/scripts/get_script_metadata": { "post": { "operationId": "postGetScriptMetadata", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true }, { "schema": { "type": "string", "default": "gzip" }, "in": "header", "name": "Accept-Encoding", "description": "For retrieving a compressed gzipped response" } ], "tags": [ "Script Execution" ], "summary": "Get Script Metadata", "description": "Get the full definitions of a specific script in the scripts library.\n\nRequired license: **Cortex XDR Pro per Endpoint** or **Cortex XDR Pro per GB**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "script_uid": "" } } }, "properties": { "request_data": { "type": "object", "required": [ "script_uid" ], "description": "A dictionary containing the API request fields.", "properties": { "script_uid": { "type": "string", "description": "Unique identifier of the script, returned by the [Get Scripts](https://app.gitbook.com/s/bcaz3nnErYwzhJKuv5Ls/cortex-xdr-3.x-apis/script-execution#post-public_api-v1-scripts-get_scripts) API per script." } } } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "script_uid": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "script_id": "