Cortex XDR

LAST UPDATE: 04/01/2024

Overview

Palo Alto Networks Cortex XDR Platform allows users to ingest alerts and to leverage alert stitching and investigation capabilities. The APIs allow the user to manage incidents in a ticketing or automation system of your choice by reviewing and editing the incident's details, status, and assignee.
D3's integration with the Palo Alto Networks Cortex XDR's latest REST API provides the ability to ingest incidents, update incidents, and data enhancement operation for incidents.

D3 SOAR is providing REST operations to function with Cortex XDR.

Cortex XDR is available for use in:

D3 SOAR	V14.5.110.0+
Category	SIEM XDR
Deployment Options	Option II, Option IV

Connection

To connect to Cortex XDR from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the Cortex XDR API instance.	https://api-{fqdn}
API Key	The API key to authenticate the API connection.	********
API Key ID	The API key ID to authenticate the API connection.	1
Version	The version of the API to use for the connection.	v1

READER NOTE

Fully Qualified Domain Name (FQDN)

Each Cortex tenant is assigned a unique host and domain name combination known as the Fully Qualified Domain Name (FQDN). When generating the API Key and Key ID, a FQDN is assigned. For more information, refer to Get Started with Cortex XDR APIs from Palo Alto's documentation.

Permission Requirements

Each endpoint in the Cortex XDR API requires a certain permission scope.

READER NOTE

As Cortex XDR is using role-based access control (RBAC), the API access keys are generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Cortex XDR console for each command in this integration.

Some features are license-dependent. Accordingly, users may not see a specific feature if the feature is not supported by the license type of their user account or if they do not have access based on their assigned role.

When creating custom roles, refer to Access Management for required permissions

For Cortex XDR predefined User roles and permissions, please refer to Predefined User Roles for Cortex XDR.

Required License:

To execute commands, Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per TB is required.

Configuring Cortex XDR to Work with D3 SOAR

Log in to Cortex XDR with your credentials.
Once logged in, click the icon and navigate to Configurations > Integrations > API Keys.
Click + New Key to create a new API key.
In the API key creation window, select the "Advanced" security level. It is recommended to uncheck the "Enable Expiration Date" option to create an unlimited API key. Choose the appropriate level of access for this API key based on the desired roles. Click Generate to generate the API key.

Copy the generated API key and store it in a secure location. Click Done to complete the process. Note that the API key will not be visible again after this step. This unique API key will be used as the API Key in the integration's connector.
In the API Keys table, locate the ID field and take note of the ID number. This ID will be used as the API Key ID in the integration's connector.
Right-click your API key and select View Examples.
Copy the domain part of the CURL example, which will serve as the Server URL in the integration's connector. The format should be: https://api-{fqdn}.

Configuring D3 SOAR to Work with Cortex XDR

Log in to D3 SOAR.
Find the Cortex XDR integration.

a. Navigate to Configuration on the top header menu.

b. Click on the Integration icon on the left sidebar.

c. Type Cortex XDR in the search box to find the integration, then click it to select it.

d. Click + Connection, on the right side of the Connections section. A new connection window will appear.

Configure the following fields to create a connection to Cortex XDR.

a. Connection Name: The desired name for the connection.

b. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

c. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.

d. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

e. Description (Optional): Add your desired description for the connection.

f. Configure User Permissions: Defines which users have access to the connection.

g. Active: Check the tick box to ensure the connection is available for use.

h. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

1. Input your Server URL.

2. Input your API Key. See step 4 of Configuring Cortex XDR to work with D3 SOAR.

3. Input your API Key ID. See step 6 of Configuring Cortex XDR to work with D3 SOAR.

4. Input your API Version. Default version is v1.

i. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.

To set up a connection health check, check the Connection Health Check tick box. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

j. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.

Test the connection.

a. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the Test Connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the Test Connection fails, please check your connection parameters and try again.

b. Click OK to close the alert window.

c. Click Add to create and add the configured connection.

Commands

Cortex XDR includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Cortex XDR API, please refer to the Cortex XDR API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Cortex XDR to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.

Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Fetch Incident

Retrieves incidents from Cortex XDR based on the specified criteria.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time of the time range to filter the retrieved incidents in UTC time. The input start time corresponds to the selected time field (i.e., creation time or modification time).	2019-12-22 00:00
End Time	Optional	The end time of the time range to filter the retrieved incidents in UTC time. The input end time corresponds to the selected time field (i.e., creation time or modification time).	2019-12-23 00:00
Time Field	Required	The time field for the Start Time and End Time parameters. The available time fields are Creation Time and Modification Time.	Creation Time
Number of Incident(s) Fetched	Optional	The maximum number of incidents to return. When the input has no value or is not a positive number, the default value of 20 will be used. The maximum value is 100.	1
Offset	Optional	The number of items to skip before starting to collect the result set. When the input has no value or is not a positive number, the default value of 0 will be used.	0
Order By	Optional	The time field (i.e. Creation Time or Modification Time) to order the returned results. The default setting is Creation Time.	Creation Time
Direction	Optional	The sorting order (i.e., Ascending or Descending) of the returned results. The default setting is Descending.	Descending
Other Filters	Optional	The array of conditions to filter the returned incidents. Each condition is defined as object within the array, consisting of the keys "field", "operator" and "value". The available filter fields are incident_id_list, description, alert_sources, status and starred. Please note that time-related fields are not supported for the "field" key. Instead, use the Start Time, End Time and Time Field parameters to define the desired time range. For more details about the input syntax for each key, refer to Get Incidents "filters" field from Palo Alto's documentation. When this parameter is defined, all other input parameters will be ignored.	[ { "field": "status", "operator": "<eq or neq>", "value": "resolved_true_positive" }, { "field": "description", "operator": "in", "value": ["descKeyword1", "descKeyword2"] }, { "field": "alert_sources", "operator": "in", "value": ["source1", "source2"] } ]

Output

Raw Data

The primary response data from the API request.

D3 modifies the original response data by including additional fields including "creationUTCTime" and "modificationUTCTime".

SAMPLE DATA

JSON

{
    "reply": {
        "total_count": 1,
        "result_count": 1,
        "incidents": [
            {
                "incident_id": "<incident ID>",
                "incident_name": "*****",
                "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,
                "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://<link to incident>",
                "starred": false,
                "hosts": [
                    "<host ID>"
                ],
                "users": [
                    "*****_1",
                    "*****_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": [
                    "Collection",
                    "Credential Access",
                    "File Name"
                ],
                "creationUTCTime": "2019-12-22 14:20:25",
                "modificationUTCTime": "2019-12-22 17:07:05"
            }
        ]
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "IncidentIDs": [*****],
    "IncidentNames": ["*****"],
    "IncidentStatuses": ["resolved_known_issue"],
    "IncidentSeverities": ["medium"]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

incident_id	incident_name	creation_time	modification_time	detection_time	status	severity	description	assigned_user_mail	assigned_user_pretty_name	alert_count	low_severity_alert_count	med_severity_alert_count	high_severity_alert_count	user_count	host_count	notes	resolve_comment	resolved_timestamp	manual_severity	manual_description	xdr_url	starred	hosts	users	incident_sources	rule_based_score	manual_score	wildfire_hits	alerts_grouping_status	mitre_tactics_ids_and_names	mitre_techniques_ids_and_names	alert_categories	creationUTCTime	modificationUTCTime
<incident ID>	*****	1577024425126	1577024425126		resolved_known_issue	medium	Memory Corruption Exploit generated by XDR Agent			1	0	1	0	1	1			1577024425126		Memory Corruption Exploit generated by XDR Agent	https://<link to incident>	False	['<host ID>']	['***_1', '***_2']	['XDR Agent', 'XDR BIOC']	342		0	Enabled	['TA0004 - Privilege Escalation', 'TA0005 - Defense Evasion', 'TA0006 - Credential Access']	['T1001.001 - Data Obfuscation: Junk Data', 'T1001.002 - Data Obfuscation: Steganography', 'T1001.003 - Data Obfuscation: Protocol Impersonation']	['Collection', 'Credential Access', 'File Name']	2019-12-22 14:20:25	2019-12-22 17:07:05

Incident Field Mapping

For this integration, the default incident fields in D3 SOAR are fixed with no built-in source fields. Users can specify the source fields as needed.

Event and Incident Intake Field Mapping

Please note that incident and event intake commands require both Event Field and Incident Field Mapping. These field mappings are the default event/incident field mappings for D3 system integrations. You can edit the provided mappings or create custom mappings as needed. Please refer to Event and Incident Intake Field Mapping for more details.

Incident Main JSON Path: $.reply.incidents

The pre-configured field mappings are detailed below:

Field Name	Source Field
Title	User to define
Description	User to define
Severity	User to define, default is “Low”
Incident Type *	User to define, default is the first Incident form in D3 SOAR system
Incident Creator	User to define
Incident Owner	User to define
Incident Playbook	User to define
Due In Date	User to define
Unique Key	User to define
Tactics	User to define
Techniques	User to define

Event Field Mapping

Main Event JSON Path

$

The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.

The pre-configured event field mappings are detailed below:

Field Name	Source Field
Unique Event Key	.incident_id
Event Name	.incident_name
Event Type	.alarmRuleName
Description	.description
Severity	.severity
Start Time	.creation_time
Status	.status

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Incident failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Filter.

Error Sample Data

Fetch Incident failed.

Status Code: 400.

Message: Invalid Filter.

Get Incident Details

Retrieves additional information on the specified incidents, including alerts and key artifacts.

READER NOTE

The parameter Incident IDs is required to run this command.

You should already have your desired Incident IDs on hand to run this command. If you don’t, you can use the Fetch Incident command with defined filters to retrieve the desired Incident IDs. The Incident IDs can be found in the raw data at the path $.reply.incidents[*].incident_id.

Input

Input Parameter	Required/Optional	Description	Example
Incident IDs	Required	The IDs of the incidents to retrieve details.	["*****"]
Alerts Limit	Optional	The maximum number of related alerts from each incident to retrieve. The default value is 1000.	3

Output

Raw Data

The primary response data from the API request.

D3 modifies the original response data by including the "incidentID" field.

SAMPLE DATA

JSON

[
    {
        "reply": {
            "incident": {
                "incident_id": "*****",
                "incident_name": "*****",
                "creation_time": 1603184209710,
                "modification_time": 1603184209710,
                "detection_time": null,
                "status": "new",
                "severity": "high",
                "description": "generated by PAN NGFW",
                "assigned_user_mail": null,
                "assigned_user_pretty_name": null,
                "alert_count": 1,
                "low_severity_alert_count": 0,
                "med_severity_alert_count": 0,
                "high_severity_alert_count": 1,
                "user_count": 0,
                "host_count": 0,
                "notes": null,
                "resolve_comment": null,
                "manual_severity": null,
                "manual_description": null,
                "xdr_url": "https://*****.paloaltonetworks.com/***",
                "starred": false,
                "hosts": null,
                "users": [],
                "incident_sources": [
                    "PAN NGFW"
                ],
                "rule_based_score": 342,
                "manual_score": null,
                "wildfire_hits": 0,
                "alerts_grouping_status": "Enabled",
                "mitre_techniques_ids_and_names": [
                    "TA0004 - Privilege Escalation",
                    "TA0005 - Defense Evasion",
                    "TA0006 - Credential Access"
                ],
                "mitre_tactics_ids_and_names": [
                    "T1001.001 - Data Obfuscation: Junk Data",
                    "T1001.002 - Data Obfuscation: Steganography",
                    "T1001.003 - Data Obfuscation: Protocol Impersonation"
                ],
                "alert_categories": [
                    "Collection",
                    "Credential Access",
                    "File Name"
                ]
            },
            "alerts": {
                "total_count": 1,
                "data": [
                    {
                        "external_id": "<external ID>",
                        "severity": "high",
                        "matching_status": "UNMATCHABLE",
                        "end_match_attempt_ts": null,
                        "local_insert_ts": 1603175431,
                        "bioc_indicator": null,
                        "matching_service_rule_id": null,
                        "attempt_counter": null,
                        "bioc_category_enum_key": null,
                        "case_id": ***,
                        "is_whitelisted": false,
                        "starred": false,
                        "deduplicate_tokens": "<token value>",
                        "filter_rule_id": null,
                        "mitre_technique_id_and_name": null,
                        "mitre_tactic_id_and_name": null,
                        "agent_version": null,
                        "agent_device_domain": null,
                        "agent_fqdn": null,
                        "agent_os_type": "NO_HOST",
                        "agent_os_sub_type": null,
                        "agent_data_collection_status": null,
                        "mac": null,
                        "agent_is_vdi": null,
                        "agent_install_type": "NA",
                        "agent_host_boot_time": null,
                        "event_sub_type": null,
                        "module_id": null,
                        "association_strength": null,
                        "dst_association_strength": null,
                        "story_id": null,
                        "event_id": null,
                        "event_type": "Network Event",
                        "event_timestamp": null,
                        "actor_process_instance_id": null,
                        "actor_process_image_path": null,
                        "actor_process_image_name": null,
                        "actor_process_command_line": null,
                        "actor_process_signature_status": "N/A",
                        "actor_process_signature_vendor": null,
                        "actor_process_image_sha256": null,
                        "actor_process_image_md5": null,
                        "actor_process_causality_id": null,
                        "actor_causality_id": null,
                        "actor_process_os_pid": null,
                        "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": "<IP address>",
                        "action_local_port": 43,
                        "action_remote_ip": "<IP address>",
                        "action_remote_port": 80,
                        "action_external_hostname": "<hostname>",
                        "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": "<serial number>",
                        "fw_url_domain": null,
                        "fw_email_subject": "",
                        "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,
                        "alert_id": "***",
                        "detection_timestamp": 1603184109000,
                        "name": "sagcalun",
                        "category": "Spyware Detected via Anti-Spyware profile",
                        "endpoint_id": null,
                        "description": "Spyware Phone Home Detection",
                        "host_ip": "<IP address>",
                        "host_name": "<hostname>",
                        "source": "PAN NGFW",
                        "action": "DETECTED_4",
                        "action_pretty": "Detected (Raised An Alert)",
                        "user_name": null,
                        "contains_featured_host": "Yes",
                        "contains_featured_user": "Yes",
                        "contains_featured_ip_address": "Yes"
                    }
                ]
            },
            "network_artifacts": {
                "total_count": 2,
                "data": [
                    {
                        "type": "DOMAIN",
                        "alert_count": 1,
                        "is_manual": false,
                        "network_domain": "<domain name>",
                        "network_remote_ip": "<IP address>",
                        "network_remote_port": *****,
                        "network_country": "UNKNOWN"
                    },
                    {
                        "type": "IP",
                        "alert_count": 1,
                        "is_manual": false,
                        "network_domain": "<domain name>",
                        "network_remote_ip": "<IP address>",
                        "network_remote_port": *****,
                        "network_country": "UNKNOWN"
                    }
                ]
            },
            "file_artifacts": {
                "total_count": 0,
                "data": []
            }
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "IncidentIDs": ["*****"],
    "AlertIDs": [***],
    "NetworkDomains": [ "<domain name>", "<domain name>" ],
    "NetworkIPAddresses": [ "<IP address>", "<IP address>" ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

incident_id	incident_name	creation_time	modification_time	detection_time	status	severity	description	assigned_user_mail	assigned_user_pretty_name	alert_count	low_severity_alert_count	med_severity_alert_count	high_severity_alert_count	user_count	host_count	notes	resolve_comment	manual_severity	manual_description	xdr_url	starred	hosts	users	incident_sources	rule_based_score	manual_score	wildfire_hits	alerts_grouping_status	mitre_techniques_ids_and_names	mitre_tactics_ids_and_names	alert_categories
*****	*****	1603184209710	1603184209710		new	high	generated by PAN NGFW			1	0	0	1	0	0					https://***.paloaltonetworks.com/*	False		[]	['PAN NGFW']	342		0	Enabled	['TA0004 - Privilege Escalation', 'TA0005 - Defense Evasion', 'TA0006 - Credential Access']	['T1001.001 - Data Obfuscation: Junk Data', 'T1001.002 - Data Obfuscation: Steganography', 'T1001.003 - Data Obfuscation: Protocol Impersonation']	['Collection', 'Credential Access', 'File Name']

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Incident Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Incident IDs Not Found.

Error Sample Data

Get Incident Details failed.

Status Code: 404.

Message: Incident IDs Not Found.

Isolate Hosts

Isolates specified endpoint(s).

READER NOTE

The parameter Endpoint IDs is required to run this command.

Run the Search Hosts command to obtain Endpoint IDs. Endpoint IDs can be found in the returned raw data at the path $.reply.endpoints[*].endpoint_id.

Input

Input Parameter

Required/Optional

Description

Example

Endpoint IDs

Required

The ID(s) of the endpoint(s) to be isolated. Endpoint IDs can be obtained using the Search Hosts command.

[

"endpint_ID"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "reply": {
        "action_id": "<action ID>",
        "status": "1",
        "endpoints_count": "673"
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Status": 1,
    "IsolatedEndpointsCount": 673
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

action_id	<action ID>
status	1
endpoints_count	673

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Isolate Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Endpoint IDs Not Found.

Error Sample Data

Isolate Hosts failed.

Status Code: 404.

Message: Endpoint IDs Not Found.

Search Hosts

Retrieves a list of filtered endpoints. The returned endpoints are sorted by last seen time in descending order. The maximum result set size is 100.

Input

Input Parameter	Required/Optional	Description	Example
Host Names	Optional	The name(s) of the endpoint(s) to be returned.	[ "host_*****" ]
User Names	Optional	The name(s) of the user(s) of the endpoint(s) to be returned.	[ "XDR" ]
Group Names	Optional	The name(s) of the group(s) of the endpoint(s) to be returned.	No sample data
Host IPs	Optional	The IP Address(es) of the endpoint(s) to be returned.	192.168.5.12
Host Status	Optional	The status of the endpoint(s) to be returned.	Connected
Platform	Optional	The platform of the endpoint(s) to be returned.	Windows
Isolated	Optional	The isolation status of the endpoints to be returned.	Isolated
Last Seen After	Optional	The endpoints which were last seen at or after this time will be returned.	2023-06-01 00:00
Last Seen Before	Optional	The endpoints which were last seen at or before this time will be returned.	2023-06-10 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "reply": {
        "total_count": 1,
        "result_count": 1,
        "endpoints": [
            {
                "endpoint_id": "<endpoint ID>",
                "endpoint_name": "<endpoint name>",
                "endpointTags": "<tag name>",
                "endpoint_type": "<endpoint type>",
                "endpoint_status": "CONNECTED",
                "os_type": "AGENT_OS_WINDOWS",
                "os_version": "8.0.xxx",
                "ip": [
                    "<IP address>"
                ],
                "ipv6": [],
                "public_ip": "<IP address>",
                "users": [
                    "XDR"
                ],
                "domain": "WORKGROUP",
                "alias": "",
                "first_seen": 1606218761377,
                "last_seen": 1606218769163,
                "content_version": "",
                "installation_package": "XDR",
                "active_directory": null,
                "install_date": 1606218762089,
                "endpoint_version": "<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": ""
            }
        ]
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "EndpointIDs": [ "<endpoint ID>" ],
    "EndpointNames": [ "<endpoint name>" ],
    "EndpointStatuses": ["CONNECTED"],
    "OSTypes": ["AGENT_OS_WINDOWS"],
    "Isolated": ["AGENT_UNISOLATED"]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

reply

{'total_count': 1, 'result_count': 1, 'endpoints': [{'endpoint_id': '<endpoint ID>', 'endpoint_name': '<endpoint name>', 'endpointTags': '<tag name>', 'endpoint_type': '<endpoint type>', 'endpoint_status': 'CONNECTED', 'os_type': 'AGENT_OS_WINDOWS', 'os_version': '8.0.xxx', 'ip': ['<IP address>'], 'ipv6': [], 'public_ip': '<IP address>', 'users': ['XDR'], 'domain': 'WORKGROUP', 'alias': '', 'first_seen': 1606218761377, 'last_seen': 1606218769163, 'content_version': '', 'installation_package': 'XDR', 'active_directory': None, 'install_date': 1606218762089, 'endpoint_version': '<version>', 'is_isolated': 'AGENT_UNISOLATED', 'isolated_date': None, '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': ''}]}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Host Names Not Found.

Error Sample Data

Search Hosts failed.

Status Code: 404.

Message: Host Names Not Found.

Unisolate Hosts

Unisolates specified endpoint(s).

READER NOTE

The parameter Endpoint IDs is required to run this command.

Run the Search Hosts command to obtain Endpoint IDs. Endpoint IDs can be found in the returned raw data at the path $.reply.endpoints[*].endpoint_id.

Input

Input Parameter

Required/Optional

Description

Example

Endpoint IDs

Required

The ID(s) of the endpoint(s) to be unisolated. Endpoint IDs can be obtained using the Search Hosts command.

[

"endpint_ID"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "reply": {
        "action_id": "<action ID>",
        "status": "1",
        "endpoints_count": "673"
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Status": 1,
    "UnisolatedEndpointsCount": 673
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

action_id	<action ID>
status	1
endpoints_count	673

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unisolate Hosts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Endpoint IDs Not Found.

Error Sample Data

Unisolate Hosts failed.

Status Code: 404.

Message: Endpoint IDs Not Found.

Update Incidents

Updates incidents in Cortex XDR.

READER NOTE

The parameter Incident IDs is required to run this command.

You should already have your desired Incident IDs on hand to run this command. If you don’t, you can use the Fetch Incident command with defined filters to retrieve the desired Incident IDs. The Incident IDs can be found in the raw data at the path $.reply.incidents[*].incident_id.

Input

Input Parameter	Required/Optional	Description	Example
Incident IDs	Required	The IDs of the incidents to update.	["*****"]
Assigned User Mail	Optional	The updated email address of the incident's assignee.	*@*.*
Assigned User Name	Optional	The updated user name of the incident's assignee. This parameter is ignored when the Assigned User Mail parameter is not defined.	Sample Name
Status	Optional	The updated status of the specified incidents.	Resolved Known Issue
Severity	Optional	The updated severity level of the specified incidents.	High
Comment	Optional	The updated comment for the specified incidents.	Comment on the incident
Update Data	Optional	The array of fields and data to update to the specified incidents. When this parameter is defined, all other input parameters will be ignored. For more details about the input syntax, refer to the "update_data" field's description in Update an Incident from Palo Alto's documentation.	{ "status": "RESOLVED_KNOWN_ISSUE", "assigned_user_mail": "sample@abc.com", "resolve_comment": "incident has been updated.", }

Output

Raw Data

The primary response data from the API request.

D3 modifies the original response data by including the "incidentID" field.

SAMPLE DATA

JSON

[
    {
        "incidentID": "*****",
        "true": "sample description"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "IncidentIDs": [*****]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

incidentID	true
*****	sample description

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Incidents failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Incident IDs Not Found.

Error Sample Data

Update Incidents failed.

Status Code: 404.

Message: Incident IDs Not Found.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cortex XDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Max retries exceeded with url: /public_api/v1/incidents/get_incidents.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Max retries exceeded with url: /public_api/v1/incidents/get_incidents.