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

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:
  1. From
    Action Center
    Scripts Library
    select
    +New Script
    .
    script-upload-1.png
    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.
  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 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.
      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
    .
    script-upload-done.png

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
\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"}] } }
Always use lower case for variable names.
  1. Fill-in 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

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 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-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.
    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
.
action-center-script-execution.png
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 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 XDR 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:
  • 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.
    script-execution-additional-data.png
  • Main results view
    —A detailed table listing all target endpoints and their details.
    script-execution-additional-data-2.png
    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

Cortex XDR allows you to select a script execution action and rerun it. When you rerun a script, Cortex XDR uses the same parameters 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.
To rerun a 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

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

Recommended For You