Cytool for Windows - Administrator Guide - 7.9 - Cortex XDR - Cortex XDR Agent - Advanced Endpoint Protection - Cortex

Abstract

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. Any changes you make using Cytool are active until the agent receives the next heartbeat communication 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

Password Required

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—Query the current interval and APEX.

checkin

—

Initiate check-in to the server.

Usage: cytool checkin

To verify the checkin, view the check-in time on the agent console.

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—Add tags to the endpoint tag list.
remove—Remove the given tags from the list of endpoint tags.
list—Display the available list of endpoint tags.

Note

Tags should be passed as one string, separated by commas, and with no spaces.

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.

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

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—Display current payload execution status.
cytool payload_execution stop—Stop 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: cytoolpersist <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\<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.

Examples:

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—Display the current status of cloud-defined proxy settings.
cytool proxy set <list>—Set 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 ""—Disable cloud-defined proxy.

quarantine

View and restore quarantined files.

Usage:

cytool quarantine list—List all quarantined files.
cytool restore <ID> [<path>]—Restore files to their original location or to a path, if specified, by specifying the file ID.

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, either Traps management service or Cortex XDR.

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

Cytool for Windows - Administrator Guide - 7.9 - Cortex XDR - Cortex XDR Agent - Advanced Endpoint Protection - Cortex - Security Operations

Cortex XDR Agent Administrator Guide

Note

Note

Note

Note