Cmd CQL glossary

A detailed guide to Cmd CQL’s operators and properties

Cmd CQL (Command Query Language) defines your reports, triggers, and searches on the sessions page. This glossary lists the CQL properties available throughout the web app, and includes several important notes on usage.

CQL usage — syntax and best practices:

  • Cmd CQL values are only listed in the web interfaces where they are available for a particular query type (e.g., session trigger queries and searches of unresolved alerts have different vocabularies).
  • Do not attempt to escape characters using the backslash: \*
    Instead, escape using square brackets: [*]
  • Cmd CQL provides a number of ways to match characters. We recommend you learn the syntax.
  • The trigger best practices guide teaches some fundamental design principles to keep in mind when building triggers.

Table of contents

This page contains glossaries of:

  

Boolean operators

You can create complex queries by joining CQL values together using Boolean search operators. For example:

(cmd_user_typed = 'true' and cmd = 'clear') and (cmd_hour_of_day < '8:00' or cmd_day_of_week IN 'saturday,sunday')

This example command trigger query would cause the trigger to fire when (a user manually typed a command and the command was “clear”) and (the command was executed either before 8am or any time on a Saturday/Sunday).

The boolean operators available for constructing queries:

Boolean operator Description
' Quotation marks are used to contain search values
() Parentheses are used to group CQL values during complex queries
and All of the queries must be true
or Any of the queries must be true

CQL operators

You can use the following CQL operators to construct queries:

CQL operator Description Example
= Equal to cmd = ‘clear’
!= Not equal to cmd != ‘clear’
< Less than. For dates and times: before. cmd_hour_of_day < ‘5:00’
> Greater than. For dates and times: after. cmd_hour_of_day > ‘5:00’
<= Less than or equal to cmd_hour_of_day <= ‘5:00’
>= Greater than or equal to cmd_hour_of_day >= ‘5:00’
IN Includes.
Do not use with wildcards like ? or *, and separate multiple values with commas, not spaces.
cmd_exec_user IN ‘root,honeypot’
NOT IN Excludes.
Do not use with wildcards like ? or *, and separate multiple values with commas, not spaces.
cmd_exec_user NOT IN ‘root,honeypot’
Learn more about the CQL syntax for matching characters.

Command queries

These CQL values are related to commands. You can use them to search session data, create reports, and build command triggers.

Query Description Example
cmd The executed command, as entered. cmd = ‘ls -la’
cmd_day_of_week The day of week the command is executed. For triggers, the date is in UTC. For all other CQL search queries, the date is based on your local time. cmd_day_of_week = ‘monday’
cmd_day_of_week IN ‘saturday,sunday’
cmd_exec_path The executable path of the command. cmd_exec_path = ‘/home/ubuntu’
cmd_exec_path NOT IN ‘/usr/*’
cmd_has_output Boolean. True for commands which generated output. cmd_has_output = ‘true’
cmd_hour_of_day The hour of day when the command was executed (in 24 hour format). In trigger queries, the date is in UTC. In all other queries, the date is based on your local time cmd_hour_of_day = ‘21:00’
cmd_hour_of_day < ‘8:00’
cmd_interactive Boolean. True for commands with a TTY. cmd_interactive = ‘true’
cmd_parameters The flags, options, etc. that were used with the command. cmd_parameters != ‘-la’
cmd_parent_cmd_root Dual-valued: The base name of parent process' exe, and the base name of LKUEP. Trigger queries can match on either value. cmd_parent_cmd_root = ‘sudo’
cmd_root The executed command, without flags, options, or arguments. cmd != ‘ls’
cmd_top_level_only Boolean. If true, your search will list only root-level commands. cmd_top_level_only = ‘true’
cmd_working_directory The executed command’s working directory. cmd_working_directory = ‘/home/ubuntu’

Session queries

Queries related to sessions. You can use them to search session data, create reports, and build session triggers.

Query
Description
Example
session_login_user The Linux user who invoked the session. session_login_user = ‘ubuntu’
session_cmd_user The Cmd username of the remote user (available if they used Cmd 2FA during the session). session_cmd_user = ‘jdoe’
session_cmd_user IN ‘jdoe,fsmith’
session_user Dual-valued. Matches on the session_login_user and the session_cmd_user. session_user IN ‘ubuntu,jsmith’
session_user_role Any Cmd user roles associated with the session_cmd_user. session_user_role = ‘dev’
session_user_role NOT IN ‘admin,ops’
session_country The country associated with the IP address that initiated the session. session_country = ‘canada’
session_country IN ‘germany,japan’
session_region The region (e.g. state, province) where the session was initiated (based on IP). Use the 2-character ISO abbreviation session_region IN ‘BC,NY,PA’
session_city The city associated with the IP address that initiated the session. session_city = ‘paris’
session_city IN ‘vancouver,london’
session_day_of_week The day of the week when the session was logged. In trigger queries, the date is in UTC. In all other queries, the date is based on your local time. session_day_of_week = ‘tuesday’
session_date_full The exact date and time when the session was initiated. You can use the date picker instead. session_date_full > ‘Jun 10,2021’
session_duration The session’s duration (in seconds). Note that even if you create a trigger to terminate sessions after a given session_duration, commands will successfully execute as long as execution begins before the time limit is reached. This avoids interrupting commands which take time to execute. session_duration >=‘60’
session_has_authenticated Boolean. True if 2FA was used during the session. session_has_authenticated = ‘true’
session_entry_mechanism The session’s entry mechanism. Can help determine how the user connected. Current values are UNKNOWN, SSH, INIT, TTY, CONSOLE, AWS_SSM and OTHER. For agents prior to 1.4.0 values are SSH, TTY and UNKNOWN session_entry_mechanism = ‘SSH’
session_interactive Boolean. True for sessions where the TTY was interactive. session_interactive = ‘true’
session_id Cmd UUID associated with the session. session_id = ‘SES-aded4574b4be1 1e9825a000c29b2846s’
session_ip IP address that initiated the connection. session_ip = ‘192.168.1.23’
session_ip NOT IN ‘192.168.1.23,172.31.55.245’
session_ip_risk Risk rating of the inception SSH session’s source IP address, according to MaxMind. From 0.01 to 99, where higher scores indicate higher risk. session_ip_risk > ‘50’
session_latitude Latitude (based on IP). session_latitude = ‘37.4043’
session_longitude Longitude (based on IP). session_longitude = ‘-95.7001’
session_uts_domain_name Domain name (as per “man 2 getdomainname”) associated with the Linux server, VM, or container in which the process is executed. session_uts_domain_name = ‘w2k’
session_uts_hostname Hostname (as per “man 2 gethostname”) associated with the Linux server, VM, or container in which the associated process is executed. May differ from the server_hostname (UTS hostname where the agent is running) when the process execution is in a container and the agent is not (such as with a Kubernetes DaemonSet configured to run in the host PID namespace). session_uts_hostname = ‘carg-kubeletl013’
Note: values for the following properties are only captured from Kubernetes deployments that use CRI-O or Containerd.
session_cri_container_name The session’s container name. session_cri_container_name = ‘nginx’
session_cri_container_image A hash of the session’s container image. session_cri_container_image = ‘sha256:bd0ad0dd8520627a4478298cd74fead558b7819167a5b40d09ea6aaee9c92153’
session_cri_container_id The session’s container runtime container ID, i.e. the CRI-O container ID. session_cri_container_id = cri-o://9a9209dc0608ce80f62bb4d7f7df61bcf8dd2abd77ef53075dee0542548238b7
session_cri_pod_name The session’s Kubernetes pod name. session_cri_pod_name = ‘cmd-nginx’
session_cri_node_name The session’s Kubernetes node name. session_cri_node_name = ‘node-1234’
session_cri_namespace The session’s Kubernetes namespace. session_cri_namespace = ‘kube-system’

Server queries

Queries related to servers. You can use them to search session data, create reports, and build triggers.

Query
Description
Example
server_added Date when the server was first monitored by Cmd. For triggers, uses UTC. Otherwise, uses your local time. Accepts Unix timestamps as integers, and date strings such as ‘last week’, ‘yesterday’, etc. server_added < ‘last week’
server_added != ‘february’
server_group The server’s server group(s). server_group != ‘prod’
server_group IN ‘demo,test’
server_has_group Boolean. True if the server belongs to a server group. server_has_group = ‘true’
server_hostname The server’s hostname. server_hostname = ‘cmd.com’
server_id The server ID that can be found on the Cmd web app’s servers settings page. server_id = ‘SVR-b371256f9ded1 1e987b80242ac110002’
server_ip The server’s IP address. server_ip = ‘192.168.1.23’
server_name The server’s name in the Cmd web app. server_name = ‘test-1’
server_name NOT IN ‘test-2,test-3’
server_session_count Number of sessions taking place on the server. server_session > ‘5’

Trigger queries

Query Description Example
trigger_name The trigger’s user-defined name. trigger_name = ‘failed_2FA’
trigger_alert_level The trigger’s alert level (0-5). trigger_alert_level = ‘5’
trigger_has_alert Boolean. True when the trigger created an alert. trigger_has_alert = ‘true’
trigger_has_notice Boolean. True when the trigger created a notice. trigger_has_notice = ‘false’

File query

The file query can be used for File Triggers and Reports.

Query Description Example
file_name The full-path to a file (wildcards are accepted). file_name = ‘fullpath/to/file’