Create custom XQL widgets - Administrator Guide - Cortex XDR - Cortex

Create custom XQL widgets - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR Documentation

Product

Cortex XDR

Creation date

2024-03-06

Last date published

2024-10-09

Notice

Custom XQL widgets are supported in Cortex XDR Pro and Cortex XSIAM only.

With custom XQL widgets you can personalize the information that you display on your custom dashboards and reports. You can build widgets that query specific information that is unique to your workflow, and define the graphical format you require (such as table, line graph, or pie chart).

All of your predefined and custom XQL widgets are available in the Widget Library under Dashboards & Reports → Customize → Widget Library. From the Widget Library, you can browse all widgets by category, create new XQL widgets, and edit and delete existing XQL widgets.

How to create a custom XQL widget

In the Widget Library, select Create custom XQL widget.
Enter a widget name and an optional description.
Define an XQL query that searches for the data you require. Select XQL Helper to view XQL search and schema examples. For more information, see How to build XQL queries.
Select Preview to review the search results.
Note
Cortex Query Language (XQL) queries generated from the Widget Library do not appear in the Query Center. The results are used only for creating the custom widget.
In the Widget section, define how you want to visualize the results.
(Optional) Add parameters to the query.
You can use parameters to filter widget data on a dashboard or report, and create drilldowns on dashboards. Base your filters on fields and values in the query results.
Take the following steps
In the search results, identify a field by which you want to filter.
Using the filter stage, define parameters prefixed with $.
To specify parameters with a single predefined value, use the = operator. To specify parameters with multiple values (predefined or dynamic), use the IN operator.
Example of a single value parameter
Example 22. Single value parameters
The following query defines the $domain parameter for filtering dashboard data by domain, based on the domain field in the agent_auditing dataset.
Single value parameters are based on static predefined values. In this example, the dashboard user will be able to select a domain from a list of predefined domains.
dataset = agent_auditing | filter domain = $domain

Example of a multiple value parameter
Example 23. Multiple value parameters
The following query defines the $endpointname parameter for filtering dashboard data by one or more endpoint names, based on the endpoint_name field in the agent_auditing dataset.
You can configure this parameter with static predefined values, or dynamic values that are pulled from an XQL query.
dataset = agent_auditing | filter endpoint_name IN ($endpointname)

(Optional) Under Assign Parameters (default values), define default values for the parameters. When you add the widget to a dashboard or report, the data will be automatically populated. Alternatively, you can configure all input values when you set up a dashboard or report.
(Optional) Specify a time frame. The default time frame is 1M.
Save the widget.
The custom widget appears in the list of existing widgets.

Notice

Note