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. 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 MS-DOS 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.
Starting with the Cortex XDR agent 7.4 release for Windows, the new
cyserver.exe
process includes and replaces the previous
CyveraService.exe
,
tlaservice.exe
, and
twdservice.exe
high-privileged processes.
Command Option
Password Required
Description
enum
Enumerate protected processes.
Usage:
cytool enum
For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool enum
Process ID Agent Version 4448 7.0.0.27797 1188 7.0.0.27797 10980 7.0.0.27797 1160 7.0.0.27797 11756 7.0.0.27797 11080 7.0.0.27797 11432 7.0.0.27797 9432 7.0.0.27797 9424 7.0.0.27797 9752 7.0.0.27797 9404 7.0.0.27797 11872 7.0.0.27797 12272 7.0.0.27797 6864 7.0.0.27797 12532 7.0.0.27797
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.
protect
Enable or disable a protection feature.
Usage:
cytoolprotect
<action>
<feature>
where:
  • <action>
    —Changes protection for an agent feature. Options are:
    enable
    ,
    disable
    ,
    policy
    , and
    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, and
    service
    for agent services.
For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool protect disable process
Enter supervisor password: Protection Mode State Process Disabled Disabled Registry Policy Enabled File Policy Enabled Service Policy Enabled
startup
Enable, disable, or query the startup state of the Cortex XDR agent components.
Usage:
cytool startup
<action>
<component>
where:
  • <action>
    —Changes startup action for an agent component. Options are:
    enable
    ,
    disable
    , and
    query
    . The query option displays the startup status for each component.
  • <component>
    —Specifies the component for which you want to change the startup action. To change the startup action for multiple components, list them with spaces separating each component. Options are:
    cyverak
    ,
    cyvrmtgn
    ,
    cyvrfsfd
    ,
    cyserver
    , and
    telam
    .
For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool startup disable cyverak cyvrfsfd
Enter supervisor password: Service Startup cyverak Disabled cyvrmtgn System cyvrfsfd Disabled cyserver Automatic telam Automatic
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
policy
Query or compare the applied policy for a process.
Usage:
cytool policy
<action>
<process>
where:
  • <action>
    —Options are:
    query
    and
    compare
    . The
    query
    option displays the current applied policy for the process; the
    compare
    option enables you to compare the policy against the policy for another process or against the default policy.
  • <process>
    —Either the process name or process ID (PID).
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 [...]
For example, 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 [...]
trace
Operate product trace sessions.
Usage:
  • cytool trace start
    <log size>
    —Starts the trace session and logs the results to a file with a maximum
    <logsize>
    in MB (up to 25MB).
  • cytool trace stop
    —Stops the trace session.
  • cytool trace reset
    —Resets all tracing configurations to their default values. If an active logging session exists, Cytool will restart the session.
  • cytool trace set
    <component>
    <level>
    <flag>
    , where:
    • <component>
      can be either
      all
      (set the log level for all components) or one of the following individual components:
      cyvrlpc
      ,
      cyvrfsfd
      ,
      cyverak
      ,
      cyvrmtgn
      ,
      cyreport
      ,
      cyserver
      ,
      cyapi
      ,
      cylnk
      ,
      cyrprtui
      ,
      cytray
      ,
      tlacore
      ,
      cytool
      ,
      cyverau
      ,
      cyinjct
      ,
      cyvrtrap
      ,
      cyvera
      ,
      ntnativeapi
      ,
      winutils
      , or
      panwd
      .
    • <level>
      can be one of the following log levels:
      NONE
      ,
      CRITICAL
      ,
      ERROR
      ,
      WARNING
      ,
      INFO
      ,
      VERBOSE
      ,
      DEBUG
      , or
      ALL
      .
    • <flag>
      is the mask (hex) of one or more trace flags (a maximum of 31) separated by spaces that the agent assigns to each trace when a program runs on the endpoint (for example
      0x7FFFFFFF
      , or
      0x5
      ). The trace flag is a property of a trace provider (in this case, Cortex XDR) and determines which events the agent generates. You can use the trace flag to filter events that the agent traces.
  • cytool trace convert <etl_file> [<tmf_file>]
    —Extract the encoded event trace log (ETL) file using a trace message format (TMF) file as a key to a file with the same name and store the result in
    %ProgramData%\Cyvera\Logs\Log.txt
    . When a TMF file is not supplied, Cytool uses the default TMF file stored in the
    %ProgramData\Cyvera\Logs\
    folder to convert the ETL file.
    This command is not supported on Windows XP SP3.
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.
stat
Query Cortex XDR agent statistics from a running process.
Usage:
cytoolstat
<pid>
where
<pid>
is the process ID (PID).
For example, to display statistics about the Chrome process identified by PID 4080:
c:\Program Files\Palo Alto Networks\Traps>
cytool stat 4080
DllSec Invocations: 0 DllSec Time: 00:00:00.0 G01 Invocations: 0 G01 Time: 00:00:00.0 G01 Thunk 00 Resolution: 0 G01 Thunk 01 Resolution: 0 G01 Thunk 02 Resolution: 0 G01 Thunk 03 Resolution: 0 G01 Thunk 04 Resolution: 0 G01 Thunk 05 Resolution: 0 G01 Thunk 06 Resolution: 0 G01 Thunk 07 Resolution: 0 G01 Thunk 08 Resolution: 0 G01 Thunk 09 Resolution: 0 G01 Thunk 10 Resolution: 0 G01 Thunk 11 Resolution: 0 G01 Thunk 12 Resolution: 0 G01 Thunk 13 Resolution: 0 G01 Thunk 14 Resolution: 0 G01 Thunk 15 Resolution: 0 G01 Stack Walk Resolution: 0 J01 Minimum Stack Depth: 166 J01Checks: 25 J01 Stack Walk Checks: 0
tla
View the history of the agent local analysis module.
Usage:
cytool tla query
For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool tla query
Model: PE Build: 1800 Timestamp: Tuesday, November 26, 2019, 15:23:20 Model: Visual Basic Application Macro Build: 1801 Timestamp: Tuesday, November 26, 2019, 12:40:07
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. For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool info
Cortex XDR (R) supervisor tool 7.0.0.27797 (c) Palo Alto Networks, Inc. All rights reserved General Cortex XDR information. USAGE: cytool info query C:\Program Files\Palo Alto Networks\Traps>
cytool info query
Content Type: 113 Content Build: 18279 Content Version: 113-18297 Event Log: 1
wf
Local verdicts cache operations.
Usage:
cytool wf query [<hash>]
C:\Program Files\Palo Alto Networks\Traps>
cytool wf query 6D712E38945275FC534042191B02A8B34AA1CCED82486C98C1CE8935DDCF
Enter supervisor password: Hash,Verdict,Override,Local Verdict,Model Version,Size,Type,Path,Time Stamp,Publishers 6d712e38945275fc534042191b02a8b34aa1cced82486c98c1ce8935ddcf, Unknown(2),No Override,Malware(1),593,55296,Executable(1), "\\?\C:\Users\admin\AppData\Local\Packages\Microsoft. MicrosoftEdge_8wekyb3d8bbwe\TempState\Downloads\test-pe.exe", "Monday, July 12, 2019, 20:14:07","",Root,
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 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
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.
For 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 : ...m.BubbleWitch3Saga_6.1.0_x86__kgqvnymyfvs32\res_output\particles\collected_counter_feathers.xml The operation completed successfully. C:\Program Files\Palo Alto Networks\Traps>
cytool scan stop
Enter supervisor password: The operation completed successfully.
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>
:
  • 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.
C:\Program Files\Palo Alto Networks\Traps>
cytool persist list
Enter supervisor password: Persistent database list: security_events.db Database of security events (preventions) file_upload.db Database of files being uploaded to ESM hash_containers.db Database of files and containers hash_paths.db Database of file paths agent_actions.db Database of one time actions agent_settings.db Database of agent settings esm_frontend.db Database of ESM frontend settings esm_reports.db Database of ESM reports cloud_frontend.db Database of Cloud frontend settings cloud_reports.db Database of Cloud reports post_detection.db Database of post-detection candidates remediation_events.db Database of remediation events C:\Program Files\Palo Alto Networks\Traps>
cytool persist export file_upload.db
Enter supervisor password: persistence::DB: C:\ProgramData\Cyvera\LocalSystem\persistence\file_upload.db: Open persistence::DB: C:\ProgramData\Cyvera\LocalSystem\persistence\file_upload.db: Close
log
Set log level for the desired process.
Usage:
cytool log set_level <log_level> <components>
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
    all
    or it can be one or more of the following agent components:
    trapsd
    ,
    authorized
    ,
    pmd
    , or
    cortex xdr
    .
Then use the
cytool log collect
command to generate a support file archive of all logs in a TGZ file.
checkin
Initiate check-in to the server.
Usage:
cytool checkin
To verify the checkin, view the check-in time on the agent console.
last_checkin
Display the time of the last successful check-in.
Usage:
cytool last_checkin
For example:
C:\Program Files\Palo Alto Networks\Traps>cytool last_checkin Persistent Last Check-In time Database agent_settings: persistence::DB: C:\ProgramData\Cyvera\LocalSystem\Persistence\\agent_settings.db: Open persistence::DB: C:\ProgramData\Cyvera\LocalSystem\Persistence\\agent_settings.db: Open: IO error: C:\ProgramData\Cyvera\LocalSystem\Persistence\\agent_settings.db\LOCK: Could not lock file. Last Check-In time (UTC): 2020-01-27T09:53:50Z Last Check-In time (local): 2020-01-27T11:53:50Z Total: 1 records persistence::DB: C:\ProgramData\Cyvera\LocalSystem\Persistence\\agent_settings.db: Close
edr
EDR operations.
Usage:
  • cytool edr stats
    —Display EDR stats collected on the endpoint.
payload_execution
Stop or query payload execution status. Relates to Live Terminal and script execution.
Usage:
  • cytool payload_execution quey
    —Display current payload execution status.
    For example:
  • cytool payload_execution quey
    —Stop payload execution.
websocket
Display current websocket connection status.
Usage:
cytool websocket query
For example:
C:\Program Files\Palo Alto Networks\Traps>
cytool websocket query
Current status of websocket connection is: server: wss://ch-panw-61-beta.traps.paloaltonetworks.com/operations/socket connected: true enabled: true uptime: 00:39:46.444
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.
vdi
Perform VDI operations.
Usage:
cytool vdi
<operation>
where
<operation>
is currently only:
  • update
    —Update the golden image name and ID in the persistent database.
For example:
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.
event_collection
Start or stop event collection (EDR/DSE).
Usage:
cytool event_collection
<operation>
  • cytool event_collection query
    —Display current event collection status.
  • cytool event_collection enable
    —Start or stop event collection as set by policy.
  • cytool event_collection disable
    —Forcibly stop event collection.
  • cytool event_collection logstat
    —Write internal statistics to the log file.
isolate
Release endpoint from network isolation.
Usage:
cytool isolate stop

Recommended For You