Cytool for Windows

To manage Traps functions from the command line on Windows endpoints, use Cytool.

Cytool is a command-line interface (CLI) that is integrated into the Cortex XDR agent and enables you to query and manage both basic and advanced functions of the agent. Unless stated otherwise, changes you make using Cytool take effect when the agent receives the next heartbeat communication (every five minutes) from Cortex XDR.

On Windows endpoints, you can access Cytool using a Microsoft command prompt that you run as an administrator. Cytool is located in the C:\Program Files\Palo Alto Networks\Traps folder on the endpoint.

The following table displays the Cytool options available on Windows endpoints. Where there is a password required for admin commands, this is the same password as was defined as the Uninstall Password.

Note

Since the Cortex XDR agent 7.6 release for Windows, the cyserver.exe process includes and replaces the previous CyveraService.exe, tlaservice.exe, and twdservice.exe high-privileged processes.

Command Option	Description
adaptive_policy	Adaptive policy agent commands Usage cytool adaptive_policy [interval <seconds | policy> | collect_stats | recalc | query] Where: interval —Sets a recalculation interval override (in seconds), or resets an override. Options are: seconds/policy. collect_stats—Initiates a collection of internal statistics. recalc—Triggers a recalculation of the adaptive policy. query—Querys the current interval and APEX.
cert_enforcement	Perform Certificate enforcement related operations. Usage: cytool cert_enforcement <operation> Where <operation> is one of the following: query—Displays current enforcement status disable—Forcibly disables enforcement policy—Sets enforcement by policy import <certificate file path>—Imports a proprietary certificate in PEM format as root CA import clear —Clears all custom root CA certificates.
checkin	Initiate check-in to the server. Usage: cytool checkin To verify the checkin, view the check-in time on the agent console.
clean_and_install	Trigger the XDR Health Helper service to remediate corrupted agent installations or failed upgrades by removing the existing agent and performing a fresh installation. Usage: cytool clean_and_install [-cs "<options_json>"] Where <options_json> can include one of the following execution modes: {"ExecutionMode":0} — Removes and reinstalls the current version of the agent. {"ExecutionMode":1} — Attempts to upgrade to the desired version and stops if the upgrade fails. {"ExecutionMode":2} — (Default) Attempts to upgrade to the desired version and falls back to reinstalling the current version if the upgrade fails. For example: cytool clean_and_install -cs "{\"ExecutionMode\":0}"
edr	Display EDR stats collected on the endpoint. Usage: cytool edr stats
endpoint_tags	Use Endpoint Tags to identify groups of endpoints. Usage: cytool endpoint_tags <action> Where action can be: add—Adds tags to the endpoint tag list. remove—Removes the given tags from the list of endpoint tags. list—Displays the available list of endpoint tags. Note Tags should be passed as one string, separated by commas, and with no spaces. For example: cytool endpoint_tags add "tag1[,tage2,...,tagN]" cytool endpoint_tags remove "tag1[,tage2,...,tagN]" cytool endpoint_tags list "tag1[,tage2,...,tagN]"
enum	Enumerate protected processes. Usage: cytool enum Note If you change the action mode for protected processes in the Exploit Security Profile in Cortex XDR, you must restart the protected processes for the security policy to be enforced on the processes and its forked processes, and only then you will see them on this list.
event_collection	Perform event collection (EDR/DSE) operations. Usage: cytool event_collection <operation> Where <operation> can be: query—Displays the current event collection status. enable—Start or stop event collection as set by policy. disable—Forcibly stops event collection. logstat—Writes internal statistics to the log file.
image	Display information about a PE file (executable or DLL). Usage: cytool image <filename> For example: C:\Program Files\Palo Alto Networks\Traps> cytool image json.dll Image Information Location: json.dll Size: 176.98 KB (181224 bytes) File SHA256: a46b8e1ad9a808fb09e7b79bd03b66a611d0c7aa71291c216be555af14d16421 Architecture: x86-64 Subsystem: Windows GUI PE Size: 156.00 KB (159744 bytes) PE SHA256: 8cbca46419bf7260c99aaa3c73a6944e97f5c5b053a8b88e9a17367439b08d7d
imageprep	Prepare a golden image by submitting files for cloud analysis and generate a threats report. Usage: cytool imageprep [scan] [timeout <scan timeout>][upload <upload timeout>] [path <full path>] where: <scan timeout>—The number of hours the scan is permitted to run before reporting an error. <upload timeout>—The number of minutes the agent can take to upload unknown files to Cortex XDR before reporting an error. <full path>—Path to store the scan report. If no path is specified, Cytool saves the scan report to the local Cytool directory. To save files to this folder, you must first disable service protection using the cytool protect disable command. For example: C:\Program Files\Palo Alto Networks\Traps> cytool imageprep scan timeout 4 upload 60 path c:\report Start Time : 17:56:46 Elapsed Time : 00:04:17 State : Running Scanned Files : 5427 Suspicious Files : 0 Failed Files : 9 Volume Root Path : \\?\C:\ Window Usage : 0 236 20000 Path : ...t\cache2\entries\9B982CE198BF046E6CCF25478920DDFD9E5842E5 Scan completed successfully Complete report can be found at: C:\report\imageprep_2019-03-06_08-59-30.xml
import	Import pre-downloaded content or local support exceptions. Used for solving specific problems with a support representative.
info	Display general Cortex XDR agent information. Usage: cytool info [query] To display the agent version, run the cytool info command without any additional arguments. To display additional details about the agent, such as the version of the default policy and the specific build number, add the query argument.
isolate	Release endpoint from network isolation. Usage: cytool isolate stop
last_checkin	Display the time of the last successful check-in. Usage: cytool last_checkin
log	Set log level for the desired process/Generate support file archive. Usage: cytool log set_level <log_level> <Components|all> where: <log_level>—An integer value corresponding to the log level: 0—Disable logging 1—Fatal 2—Critical 3—Error 4—Warning 5—Notice 6—Information 7—Debug 8—Trace <Components> can be cyserver or all Use cytool log collect to generate a support file archive of all logs in a TGZ file.
payload_execution	Stop or query payload execution status. Relates to Live Terminal and script execution. Usage: cytool payload_execution query—Displays current payload execution status. cytool payload_execution stop—Stops payload execution.
persist	The Cortex XDR agent stores policy and security event information, such as the list of trusted signers, local verdicts, and one-time actions in local databases on the endpoint. To troubleshoot policy issues and security events, you can use cytool persist operations to import, export, and view information stored in the local database. Usage: cytool persist <action> Where <action> can be: list—Lists the local databases on the endpoint. export [<database name> | <databasepath>]—Exports the database table to a file in the C:\Users&#x3C;user>\Documents\PaloAltoNetworks\Traps\cytool directory. import [<database name> | <databasepath>] <file name>—Adds the records in a JSON file to the database. print <database name> | <databasepath> [csv]—Prints the records in the database to a CSV file. To view a list of all local databases, use the cytool persist list command.
policy	Query or compare the applied policy for a process. Usage: cytool policy [query | compare] [process [process]] where: Options are: query—Displays the current applied policy for the process. compare —Compares the policy against the policy for another process, or against the default policy. <process>—Either the process name or process ID (PID). Note: If an image name is specified, a new policy is generated as if the process was created. If a process ID is specified, the system queries the effective policy for the running process. For example: To query the policy for future executions of notepad.exe: C:\Program Files\Palo Alto Networks\Traps> cytool policy query notepad.exe Enter supervisor password: Generic Enable 0x00000001 LongHooks 0x00000000 StaticHooks 0x00000000 NoCallSplitting 0x00000000 InitSecurityCookie 0x00000000 DontInjectThinApp 0x00000001 LeanInjection 0x00000000 B01 Enable 0x00000000 BlockAPI 0x00000000 [...] To compare the policy for future executions of notepad.exe to the default policy: C:\Program Files\Palo Alto Networks\Traps> cytool policy compare notepad.exe default Enter supervisor password: Generic Enable 0x00000001 0x00000001 LongHooks 0x00000000 0x00000000 StaticHooks 0x00000000 0x00000000 NoCallSplitting 0x00000000 0x00000000 InitSecurityCookie 0x00000000 0x00000000 DontInjectThinApp 0x00000001 0x00000001 LeanInjection 0x00000000 0x00000000 B01 Enable 0x00000000 0x00000000 BlockAPI 0x00000000 0x00000000 [...] cytool policy query 1337 Query the policy of process with ID 1337. cytool policy compare notepad.exe 1337 Compare notepad's and process ID 1337 policies.
protect	Enable or disable a protection feature. Usage: cytool protect <Action> <Feature> where: <Action>—Changes protection for an agent feature. Options are: enable disable policy query The query option displays the protection status for each feature. <Feature>—Specifies the feature for which you want to change the protection status. Options are: Process, for agent core processes Registry, for agent registry keys File, for agent files Service, for agent services Pipe, for protection of agent pipes. For example: To disable registry protection, cytool protect disable registry To enable all protection, cytool protect enable To set protection according to policy, cytool protect policy Note Any protection state change made by Cytool persists until the next reboot and is set according to the policy one hour after reboot.
proxy	Set or query cloud-defined proxies for the agent. Usage: cytool proxy query—Displays the current status of cloud-defined proxy settings. cytool proxy set <list>—Sets cloud-defined proxy settings to the proxies defined in <list>. For example: cytool proxy set "192.168.50.1:8080,192.168.60.2:808" cytool proxy set ""—Disables cloud-defined proxy.
quarantine	View and restore quarantined files. Usage: cytool quarantine list—Lists all quarantined files. cytool restore <ID> [<path>]—Restores files to their original location or to a path, if specified, by specifying the file ID.
queryall	Display a list of imported certificates for troubleshooting purposes.
reconnect	Try reconnecting to the server if communication has been disabled, or force registration with a new distribution_id. Usage: cytool reconnect—Reconnects the Cortex XDR agent to the management application on the server. cytool reconnect [force <distribution_id]> Note The distribution_id must belong to an installation package for the same operating system, and for the same or an earlier agent version than the one currently installed.
runtime	Stop or start product components. Usage: cytool runtime <Action> <Component> where: <Action>—Changes startup runtime action for an agent component. Options are: start, stop, and query. The query option displays the startup status for each component. <Component>—Specifies the component for which you want to change the runtime action, or you can specify all components by not including any in this command. To change the runtime action for a subset of components, list them with spaces separating each component. Options are: cyverak, cyvrmtgn, cyvrfsfd, and cyserver. For example: C:\Program Files\Palo Alto Networks\Traps>cytool runtime stop cyserver cyverak Enter supervisor password: Service State cyverak Stopped cyvrmtgn Running cyvrfsfd Running cyserver Stopped
scan	Scan operations. Usage: cytool scan <Action> Where <action>: start—Scans the endpoint for malware. stop—Stops a scan. query—Displays the progress if a system scan is active. last_scan_time—Displays the last time a scan was done. Example: C:\Program Files\Palo Alto Networks\Traps> cytool scan start Enter supervisor password: The operation completed successfully. C:\Program Files\Palo Alto Networks\Traps> cytool scan query Enter supervisor password: Start Time : 9:09:0648 Elapsed Time : 00:00:51 State : Running Scanned Files : 3944 Suspicious Files : 0 Failed Files : 1?\C: Volume Root Path : \?\C:\ 8 20000 Window Usage : 0 14 20000 Path : ...