Run Scripts on an Endpoint

Execute Python scripts from Cortex XDR directly on the endpoint to perform actions, retrieve data, and retrieve files.

For enhanced endpoint remediation and endpoint management, you can run Python 3.7 scripts on your endpoints directly from Cortex XDR. For commonly used actions, Cortex XDR provides pre-canned scripts you can use out-of-the-box. You can also write and upload your own Python scripts and code snippets into Cortex XDR for custom actions. Cortex XDR enables you to manage, run, and track the script execution on the endpoints, as well as store and display the execution results per endpoint.

The following are pre-requisites to executing scripts on your endpoints:

Cortex XDR Pro Per Endpoint license

Endpoints running the Cortex XDR agent 7.1 and later releases. Since the agent uses its built-in capabilities and many available Python modules to execute the scripts, no additional setup is required on the endpoint.

Role in the hub with the following permissions to run and configure scripts:

Run Standard scripts

Run High-risk scripts

Script configuration
(required to upload a new script, run a snippet, and edit an existing script)

Scripts
(required to view the

Scripts Library

and the script execution results)

Running snippets requires both

Run High-risk scripts

and

Script configuration

permissions. Additionally, all scripts are executed as System User on the endpoint.

Use the following work flow to start running scripts on your endpoints:

Manage All Scripts in the Scripts Library

Upload Your Scripts

Run a Script on Your Endpoints

Track Script Execution and View Results

Troubleshoot Script Execution

Disable Script Execution

Manage All Scripts in the Scripts Library

All your scripts are available in the

Action Center

Scripts Library

, including pre-canned scripts provided by Palo Alto Networks and custom scripts that you uploaded. From the

Scripts Library

, you can view the script code and meta data.

The following table describes both the default and additional optional fields that you can view in the

Scripts Library

per script. The fields are in alphabetical order.

Field	Description
Compatible OS	The operating systems the script is compatible with.
Created By	Name of the user who created the script. For pre-canned scripts, the user name is Palo Alto Networks.
Description	The script description is an optional field that can be filled-in when creating, uploading, or editing a script.
Id	Unique ID assigned by `Cortex` `XDR` that identifies the script.
Modification Date	Last date and time in which the script or its attributes were edited in `Cortex` `XDR`.
Name	The script name is a mandatory filed that can be filled-in when creating, uploading, or editing a script.
Outcome	High-risk —Scripts that may potentially harm the endpoint. Standard —Scripts that do not have a harmful impact on the endpoint.
Script FileSHA256	The SHA256 of the code file.

From the

Scripts Library

, you can perform the following additional actions:

Download script
—To see exactly what the script does, right-click and

Download

the Python code file locally.

View / Download definitions file
—To view or download the script meta-data, right-click the script and select the relevant option.

Run
—To run the selected script, right-click and select

Run

. Cortex XDR redirects you to the

Action Center

with the details of this script already populating the new action fields.

Edit
—To edit the script code or meta-data, right-click and

Edit

. This option is not available for pre-canned scripts provided by Palo Alto Networks.

By default, Palo Alto Networks provides you with a variety of pre-canned scripts that you can use out-of-the-box. You can view the script, download the script code and meta-data, and duplicate the script, however you cannot edit the code or definitions of pre-canned scripts.

The following table lists the pre-canned scripts provided by Palo Alto Networks, in alphabetical order. New pre-canned scripts are continuously uploaded into Cortex XDR though content updates, and are labeled

New

for a period of three days.

Script name	Description
delete_file	Delete a file on the endpoint according to the full path.
file_exists	Search for a specific file on the endpoint according to the full path.
get_process_list	List CPU and memory for all processes running on the endpoint.
list_directories	List all the directories under a specific path on the endpoint, You can limit the number of levels you want to list.
process_kill_cpu	Set a minimum CPU value and kill all process on the endpoint that are using higher CPU.
process_kill_mem	Set a minimum RAM usage in bytes and kill all process on the endpoint that are using higher private memory.
process_kill_name	Kill all processes by a given name.
*registry_delete (`Windows`)	Delete a Registry key or value on the endpoint.
*registry_get (`Windows`)	Retrieve a Registry value from the endpoint.
*registry_set (`Windows`)	Set a Registry value from the endpoint.

*Since all scripts are running under System context, you cannot perform any Registry operations on user-specific hives (HKEY_CURRENT_USER of a specific user).

Upload Your Scripts

You can write and upload additional scripts to the

Scripts Library

To upload a new script:

From

Action Center

Scripts Library

select

+New Script

Drag and drop your script file, or browse and select it. During the upload, Cortex XDR parses your script to ensure you are using only Python modules supported by Cortex XDR. Click

Supported Modules

if you want to view the supported modules list. If your script is using unsupported Python modules, or if your script is not using proper indentation, Cortex XDR will require that you fix it.

You can use the editor to update your script directly in Cortex XDR.

Add meta-data to your script.

You can fill-in the fields manually, and also upload an existing definitions file in the supported format to automatically fill-in some or all of the definition. To view the manifest format and create your own, see Creating a Script Manifest.

General

—The general script definitions include: name and description, risk categorization, supported operating systems, and timeout in seconds.

Input

—Set the starting execution point of your script code. To execute the script line by line, select

Just run

. Alternatively, to set a specific function in the code as the entry point, select

Run by entry point

. Select the function from the list, and specify for each function parameter its type.

Output

—If your script returns an output, Cortex XDR displays that information in the script results table.

Single parameter
—If the script returns a single parameter, select the

Output type

from the list and the output will be displayed as is. To detect the type automatically, select

Auto Detect

Dictionary
—If the script returns more than a single value, select

Dictionary

from the

Output type

list. By default, Cortex XDR displays in the script results table the dictionary value as is. To improve the script results table display and be able to filter according to the returned value, you can assign a user friendly name and type to some or all of your dictionary keys, and Cortex XDR will use that in the results table instead.

To retrieve files from the endpoint, add to the dictionary the

files_to_get

key to include an array of paths from which files on the endpoint will be retrieved from the endpoint.

When you are done,

Create

the new script.

The new script is uploaded to the

Scripts Library

Creating a Script Manifest

The script manifest file you upload into Cortex XDR has to be a single-line textual file, in the exact format explained below. If your file is structured differently, the manifest validation will fail and you will be required to fix the file.

For the purpose of this example, we are showing each parameter in a new line. However, when you create your file, you must remove any

characters.

This is an example of the manifest file structure and content:

{
"name":"script name",
"description":"script description",
"outcome":"High Risk|Standard",
"platform":"Windows,macOS,Linux",
"timeout":600,
"entry_point":"entry_point_name",
"entry_point_definition":{
		"input_params":[
			{"name":"registry_hkey","type":"string"},
			{"name":"registry_key_path","type":"number"},
			{"name":"registry_value","type":"number"}],
		"output_params":{"type":"JSON","value":[
			{"name":"output_auto_detect","friendly_name":"name1","type":"auto_detect"},
			{"name":"output_boolean","friendly_name":"name2","type":"boolean"},
			{"name":"output_number","friendly_name":"name3","type":"number},
			{"name":"output_string","friendly_name":"name4","type":"string"},
			{"name":"output_ip","friendly_name":"name5","type":"ip"}]
	}
}

Always use lower case for variable names.

Fill-in the script name and description.

You can use letters and digits. Avoid the use of special characters.

Categorize the script.

If a script is potentially harmful, set it as

High— Risk

to limit the user roles that can run it. Otherwise, set it as

Standard.

Assign the platform.

Enter the name of the operating system this script supports. The options are Windows, macOS, and Linux. If you need to define more than one, use a comma as a separator.

Set the script timeout.

Enter the number of seconds after which Cortex XDR agent halts the script execution on the endpoint.

Configure the script input and output.

Run by entry point

, you must specify the entry point name, and all input and output definitions.

The available parameter types are:

auto_detect

boolean

number

string

number_list

string_list

ip_list

To set the script to

Just run

, leave both

Entry_point

and

Entry_point_definitions

empty:

{
"name":"scrpit name",
"description":"script description",
"outcome":"High Risk|Standard",
"platform":"Windows,macOS,Linux",
"timeout":600,
"entry_point":"",
"entry_point_definition":{}
}

Run a Script on Your Endpoints

Follow this high-level workflow to run scripts on your endpoints that perform actions, or retrieve files and data from the endpoint back to Cortex XDR.

Initiate a new action to run a script.

From

Action Center

+New Action

, select

Run Script

Select an existing script or add a code snippet.

To run an existing script, start typing the script name or description in the search field, or scroll down and select it from the list. Set the script timeout in seconds and any other script parameters, if they exist. Click

Alternatively, you can insert a

Code Snippet

. Unlike scripts, snippets are not saved in the Cortex XDR

Scripts Library

and cannot receive input or output definitions. Write you snippet in the editor, fill-in the timeout in seconds, and click

Select the target endpoints.

Select the target endpoints on which to execute the script. When you’re done, click

Review the summary and run script.

Cortex XDR displays the summary of the script execution action. If all the details are correct,

Run

the script and proceed to Track Script Execution and View Results. Alternatively, to track the script execution progress on all endpoints and view the results in real-time, Run in interactive mode.

Run Scripts in Interactive Mode

When you need to run several scripts on the same target scope of endpoints, or when you want to view and inspect the results of those scripts immediately and interactively, you can run your scripts in

Interactive Mode

You can also initiate interactive mode for an endpoint directly from

Endpoints Management

In this mode, Cortex XDR enables you to track the execution progress on all endpoints in real-time, run more scripts or code snippets as you go, and view the results of these scripts all in one place.

Interactive Mode

, Cortex XDR displays general information that includes the scope of target endpoints and a list of all the scripts that are being executed in this session. For each script on the executed scripts list, you can view the following:

The script name, date and time the script execution action was initiated, and a list of input parameters.

A progress bar that indicates in real-time the number of endpoints for which the script execution is In Progress, Failed, or Completed. When you hover over the progress bar, you can drill-down for more information about the different sub-statuses included in each group. Similarly, you can also view this information on the scripts list to the left in the form of a pie chart that is dynamically updated per script as it is being executed.

Cortex XDR does not include disconnected endpoints in the visualization of the script execution progress bar or pie chart. If a disconnected endpoint later gets connected, Cortex XDR will execute the script on that endpoint and the graphic indicators will change accordingly to reflect the additional run and its status.

Dynamic script results that are continuously updated throughout the script execution progress. Cortex XDR lists the results, and graphically aggregates results only if they have a small variety of values. When both views are available, you can switch between them.

While in

Interactive Mode

, you can continuously execute more scripts and add code snippets that will be immediately executed on the target endpoints scope. Cortex XDR logs all the scripts and code snippets you execute in

Interactive Mode

, and you can later view them in the

Action Center

To add another script, select the script from the Cortex XDR scripts library, or start typing a

Code Snippet

. Set the script timeout and input parameters as necessary, and

Run

when you are done. The script is added to the executed scripts list and its runtime data is immediately displayed on screen.

Track Script Execution and View Results

After you run a script, you see the script execution action in the

Action Center

From the

Action Center

, you can:

Track Script Execution Status

Cancel or Abort Script Execution

View Script Execution Results

Open Script Interactive Mode

Rerun a Script

Track Script Execution Status

All script execution actions are logged in the

Action Center

. The

Status

indicates the action progress, which includes the general action status and the breakdown by endpoints included in the action. The following table lists the possible status of a script execution action for each endpoint, in alphabetical order:

Status	Description
Aborted	The script execution action was aborted after it was already In Progress on the endpoint.
Canceled	The script execution action was canceled from `Cortex` `XDR` before the `Cortex` `XDR` agent pulled the request from the server.
Completed Successfully	The script was executed successfully on the endpoint with no exceptions.
Expired	Script execution actions expire after four days. After an action expires, the status of any remaining Pending actions on endpoints change to Expired and these endpoints will not receive the action.
Failed	A script can fail due to these reasons: The `Cortex` `XDR` agent failed to execute the script. Exceptions occurred during the script execution. To understand why the script execution failed, see Troubleshoot Script Execution.
In Progress	The `Cortex` `XDR` agent pulled the script execution request.
Pending	The `Cortex` `XDR` agent has not yet pulled the script execution request from the `Cortex` `XDR` server.
Pending Abort	The `Cortex` `XDR` agent is in the process of executing the script, and has not pulled the abort request from the `Cortex` `XDR` server yet.
Timeout	The script execution reached its configured time out and the `Cortex` `XDR` agent stopped the execution on the endpoint.

Cancel or Abort Script Execution

Depending on the current status of the script execution action on the target endpoints, you can cancel or abort the action for

Pending

and

In Progress

actions:

When the script execution action is

Pending

, the Cortex XDR agent has not pulled the request yet from Cortex XDR. When you cancel a pending action, the Cortex XDR server pulls back the pending request and updates the action status as

Canceled

. To cancel the action for all pending endpoints, go to the

Action Center

, right-click the action and

Cancel for pending endpoints

. Alternatively, to cancel a pending action for specific endpoints only, go to

Action Center

Additional data

Detailed Results

, right-click the endpoint(s) and

Cancel pending action

When the script execution action is

In Progress

, the Cortex XDR agent has begun running the script on the endpoint. When you abort an in progress action, the Cortex XDRR agent halts the script execution on the endpoint and updates the action status as

Aborted

. To abort the action for all

In Progress

endpoints and cancel the action for any

Pending

endpoints, go to the

Action Center

, right-click the action and

Abort and cancel execution

. Alternatively, to abort an in progress action for specific endpoints only, go to

Action Center

Additional data

Detailed Results

, right-click the endpoint(s) and

Abort for endpoint in progress

View Script Execution Results

Cortex XDR logs all script execution actions, including the script results and specific parameters used in the run. To view the full details about the run, including returned values, right-click the script and select

Additional data

The script results are divided into two sections. On the upper bar, Cortex XDR displays the script meta-data that includes the script name and entry point, the script execution action status, the parameter values used in this run and the target endpoints scope. You can also download the exact code used in this run as a

file.

In the main view, Cortex XDR displays the script execution results in two formats:

Aggregated results
—A visualization of the script results. Cortex XDR automatically aggregates only results that have a small variety of values. To see how many of the script results were aggregated successfully, see the counts on the toggle (for example, aggregated results 4/5). You can filter the results to adjust the endpoints considered in the aggregation. You can also generate a PDF report of the aggregated results view.

Main results view
—A detailed table listing all target endpoints and their details.

In addition the endpoint details (name, IP, domain, etc), the following table describes both the default and additional optional fields that you can view per endpoint. The fields are in alphabetical order.

Field	Description
* Returned values	If your script returned values, the values are also listed in the additional data table according to your script output definitions.
Execution timestamp	The date and time the `Cortex` `XDR` agent started the script execution on the endpoint. If the execution has not started yet, this field is empty.
Failed files	The number of files the `Cortex` `XDR` agent failed to retrieve from the endpoint.
Retention date	The date after which the retrieved file will no longer be available for download in `Cortex` `XDR`. The value is 90 days from the execution date.
Retrieved files	The number of files the `Cortex` `XDR` successfully retrieved from the endpoint.
Status	See the list of statuses and their descriptions in Track Script Execution Status.
Standard output	The returned stdout

For each endpoint, you can right-click and download the script

stdout

, download retrieved files if there are any, and view returned exceptions if there are any. You can also

Export to file

to download the detailed results table in

TSV

format.

Open Script Interactive Mode

In Interactive Mode, Cortex XDR enables you to dynamically track the script execution progress on all target endpoints and view the results as they are being received in real-time. Additionally, you can start executing more scripts on the same scope of target endpoints.

To initiate

Interactive Mode

for an already running script:

From the

Action Center

, right-click the execution action of the relevant script and select

Open in interactive mode

Rerun a Script

From the

Action Center

, right-click the script you want to rerun and select

Rerun

You are redirected to the final summary stage of the script execution action.

Run the script.

To run the script with the same parameters and on the same target endpoints as the previous run, click

Done

. To change any of the previous run definitions, navigate through the wizard and make the necessary changes. Then, click

Done

. The script execution action is added to the

Action Center

Troubleshoot Script Execution

To understand why a script returned

Failed

execution status, you can do the following:

Check script exceptions
—If the script generated exceptions, you can view them to learn why the script execution failed. From the

Action Center

, right click the

Failed

script and select

Additional data

. In the

Script Results

table, right-click an endpoint for which the script execution failed and select

View exceptions

. The Cortex XDR agent executes scripts on Windows endpoints as a SYSTEM user, and on Mac and Linux endpoints as a root user. These context differences could cause differences in behavior, for instance when using environment variables.

Validate custom scripts
—When a custom script you uploaded failed and the reason the script failed is still unclear from the exceptions, or if the script did not generate any exceptions, try to identify whether it failed due to an error in Cortex XDR or due to an error in the script. To identify the error source, execute the script without the Cortex XDR agent on the same endpoint with regular Python 3.7 installation. If the script execution is unsuccessful, you should fix your script. Otherwise, if the script was executed successfully with no errors, please contact Palo Alto Networks support.

Disable Script Execution

If you want prevent Cortex XDR from running scripts on a Cortex XDR agent, you can disable this capability during agent installation or later on through Cortex XDR Endpoint Administration. Disabling script execution is irreversible. If you later want to re-enable this capability on the endpoint, you must re-install the Cortex XDR agent. See the Cortex XDR Agent Administrator’s Guide
for more information.

Disabling Script Execution does not take effect on scripts that are in progress.

Document:Cortex® XDR Pro Administrator’s Guide

Run Scripts on an Endpoint

Run Scripts on an Endpoint

Manage All Scripts in the Scripts Library

Upload Your Scripts

Creating a Script Manifest

Run a Script on Your Endpoints

Run Scripts in Interactive Mode

Track Script Execution and View Results

Track Script Execution Status

Cancel or Abort Script Execution

View Script Execution Results

Open Script Interactive Mode

Rerun a Script

Troubleshoot Script Execution

Disable Script Execution

Recommended For You

Document:Cortex® XDR Pro Administrator’s Guide

Run Scripts on an Endpoint

Run Scripts on an Endpoint

Manage All Scripts in the Scripts Library

Upload Your Scripts

Creating a Script Manifest

Run a Script on Your Endpoints

Run Scripts in Interactive Mode

Track Script Execution and View Results

Track Script Execution Status

Cancel or Abort Script Execution

View Script Execution Results

Open Script Interactive Mode

Rerun a Script

Troubleshoot Script Execution

Disable Script Execution

Recommended For You

Recommended Videos