Run scripts on an endpoint - Administrator Guide - Cortex XDR - Cortex

Run scripts on an endpoint - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR Documentation

Product

Cortex XDR

Creation date

2024-03-06

Last date published

2024-10-01

Notice

This functionality requires a Cortex XDR Pro license.

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 out-of-the-box scripts. 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.

Danger

Cortex XDR Pro Per Endpoint license
Endpoints running the Agent v7.1 and later. 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)
Note
Running snippets requires both Run High-risk scripts and Script configuration permissions. Additionally, all scripts are executed as System User on the endpoint.

All your scripts are available in the Action Center → Scripts Library, including out-of-the-box scripts and custom scripts that you uploaded. From the Scripts Library, you can view the script code and metadata.

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	Operating systems the script is compatible with.
Created By	Name of the user who created the script. For out-of-the-box scripts, the user name is Palo Alto Networks.
Description	Script description is an optional field that can be completed when creating, uploading, or editing a script.
Id	Unique ID assigned by Cortex XDR that identifies the script.
Modification Date	Date and time in which the script or its attributes were last edited.
Name	Script name is a mandatory field that can be completed 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	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 out-of-the-box scripts for your use. 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 out-of-the-box scripts.

The following table lists the out-of-the-box scripts provided by Palo Alto Networks, in alphabetical order. New scripts are continuously uploaded into Cortex XDR through 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.

Note

*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).

You can write and upload additional scripts to the Scripts Library.

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 supported Python modules. 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, you will be required to fix it. You can use the editor to update your script directly in Cortex XDR.
Add metadata to your script.
You can fill in the fields manually, or upload a definitions file in the supported format to automatically fill-in some or all of the definitions. 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.

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.

Example 14.

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

Note

In this example, we are showing each parameter in a new line. However, when you create your file, you must remove any \n or \t characters.

{
"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"}]
	}
}

Note

Always use lowercase for variable names.

How to create a script manifest

Type 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.
To 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
- ip
- 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":{}
}
```

After you run a script, you see the script execution action in the Action Center and track the 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 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 changes to Expired and these endpoints will not receive the action.
Failed	A script can fail due to these reasons: The agent failed to execute the script. Exceptions occurred during the script execution.
In Progress	The agent pulled the script execution request.
Pending	The agent has not yet pulled the script execution request from the Cortex XDR server.
Pending Abort	The 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 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 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 agent has begun running the script on the endpoint. When you abort an in progress action, the 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 py file.

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

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

In addition to 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 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 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.

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.

Open script interactive

In Run Scripts 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

Cortex XDR allows you to select a script execution action and rerun it. When you rerun a script, Cortex XDR uses the same parameter values, target endpoints, and defined timeout that were defined for the previous run. However, if the target endpoints in the original run were defined using a filter, then that filter will be recalculated when you rerun the script. Cortex XDR will use the current version of the script. If since the previous run the script has been deleted, or the supported operating system definition has been modified, you will not be able to rerun the 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.

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 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 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, contact Customer Support.