Learn more about the Cortex Query Language getrole stage that enriches events with specific roles associated with usernames or endpoints.
Important
This stage requires an Identity Threat Module license to view the results.
Syntax
getrole <field> [as <alias>]
Description
The getrole stage enriches events with specific roles associated with usernames or endpoints. The getrole stage receives as an input a String field that is either a user ID or host ID.
The roles for this field are displayed in a column called asset_roles in the results table. If there is one or more roles associated with the field, the values are represented as a string array, such as ['ADMIN', 'USER'], and are listed in the asset_roles column. If there are no roles, the resulting column is an empty array.
You can also change the name of the column using as in the syntax to define an alias: getrole <field> as <alias>.
In addition, it is possible to use the filter stage with a new ROLE prefix to display the results of a particular role using the syntax:
To include one specific role:
filter <field> = ROLE.<role name>filter array_length(arrayfilter(<field>, "@element" = ROLE.<role name> )) > 0
To include more than one specific role:
filter <field> in (ROLE.<role name1>, ROLE.<role name2>, ....)
To exclude one specific role:
filter array_length(arrayfilter(<field>, "@element" = ROLE.<role name> )) = 0
To exclude more than one specific role:
filter array_length(arrayfilter(<field>, "@element" in (ROLE.<role name1>, ROLE.<role name2>, ....))) = 0
Note
This stage is unsupported in BIOCs and real-time Correlation Rules.
Examples
Return a maximum of 100 xdr_data records with the enriched events including specific roles associated with usernames. If there are one or more roles associated with the value of the user_id string field column, the output is displayed in the asset_roles column in the results table. Otherwise, the field is empty.
dataset = xdr_data | limit 100 | getrole user_id
Return a maximum of 100 xdr_data records of all the powershell executions made by the SERVICE_ACCOUNTS user role in the organization. The first filter stage indicates how to filter for the parent process, which is powershell.exe. The fields stage indicates the field columns to include in the results table and which ones are renamed in the table: action_process_image_name to process_name and action_process_image_command_line to process_cmd. The getrole stage indicates the enriched events to include for the specific roles associated with usernames. If the ROLE.SERVICE_ACCOUNTS role is associated with any values in the actor_effective_username string field column, the row is displayed in the results table. Otherwise, the entire row is excluded from the results table.
dataset = xdr_data | filter event_type = ENUM.PROCESS and event_sub_type = ENUM.PROCESS_START and lowercase(actor_process_image_name) = "powershell.exe" | fields action_process_image_name as process_name, action_process_image_command_line as process_cmd, event_id, actor_effective_username | getrole actor_effective_username as user_roles | filter user_roles = ROLE.SERVICE_ACCOUNTS | limit 100