Run Scripts on an Endpoint - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR Pro Administrator Guide

Product
Cortex XDR
License
Pro
Creation date
2023-10-31
Last date published
2024-03-27
Category
Administrator Guide
Abstract

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

The following are prerequisites to executing scripts on your endpoints:

  • 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.

Manage All Scripts in the Scripts Library
Abstract

Manage the default and additional optional fields in the Scripts Library.

All your scripts are available in the Action CenterScripts Library, including out-of-the-box scripts 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 out-of-the-box scripts, the user name is Palo Alto Networks.

Description

The 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

Last date and time in which the script or its attributes were edited in Cortex XDR .

Name

The 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

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

Upload Your Scripts
Abstract

How to create and upload scripts.

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

To upload a new script:

  1. From Action CenterScripts 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.

  2. 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 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.

      script-upload-definitions.png
    • 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.

      script-upload-input.png
    • 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.

      script-upload-output2.png

      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.

  3. 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.

Note

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 \n or \t 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"}]
	}
}

Note

Always use lower case for variable names.

  1. Type the script name and description.

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

  2. 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.

  3. 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.

  4. Set the script timeout.

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

  5. 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":{}
    }
Run a Script on Your Endpoints
Abstract

Run scripts on your endpoints to perform actions.

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.

  1. Initiate a new action to run a script.

    From Action Center+New Action, select Run Script.

  2. Select an existing script or add a code snippet.

    1. 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 Next

    2. 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 Next

  3. Select the target endpoints.

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

  4. 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 ???. Alternatively, to track the script execution progress on all endpoints and view the results in real-time, Run Scripts 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-script-mode.png

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

    Note

    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
Abstract

After running a script, refer to the action center to see the script execution action.

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

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.

To understand why the script execution failed, see ???.

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 CenterAdditional dataDetailed 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 CenterAdditional dataDetailed 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:

  • 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 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.

Open Script Interactive Mode

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.

  1. 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.

  2. 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
Abstract

How to check why a script returned a failed execution status.

To understand why a script returned Failed execution status, you can do the following:

  1. 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.

  2. 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.

Disable Script Execution
Abstract

Disable a script execution from running on an agent.

If you want to prevent Cortex XDR from running scripts on an 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 reenable this capability on the endpoint, you must reinstall the agent. See the Cortex XDR Agent Administrator’s Guide for more information.

Note

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