Overview of widgets, including methods for creating and adding widgets. Use widgets to analyze and display data in a dashboard or report in Cortex XSOAR.
Widgets are visual components that enable you to analyze data internally or externally from Cortex XSOAR, in different formats such as graphs, pie charts, text, etc.
Cortex XSOAR comes with a number of out-of-the-box system widgets, such as Today’s New Incidents, Late Incidents, and Saved by Dbot, etc. You can edit these widgets, when creating or editing a dashboard or report.
Note
In Cortex XSOAR v6.8 and later, some content packs include a widget that tracks API rate limit errors. You can use this information for troubleshooting and to make decisions about indicator enrichment. From the Widgets Library, click + and choose SOAR Metrics from the dropdown. From the Operations tab, in the Sum field, select Total API Calls. In the Group by dropdown, select API Response Type. Note that this widget only displays data if there is an installed content pack that supports API rate limit information.
You can create widgets from the following and then add them to a dashboard or report, as required:
Widgets Library: Create a widget using the widget builder in the Widgets Library which is available for all users.
From an Incident: Create the widget from the Incidents page and then add it to a dashboard or a report.
From an Indicator: Create the widget from the Threat Intel (Indicators) page then add it to a dashboard or a report.
You can also add a custom widget in the War Room, so you can easily view the incident in a widget format, such as severity in a bar chart.
Note
If you have a significant number of widgets, performance may be affected. You should try to keep widgets simple (no scripts) and refresh times higher than one minute whenever possible.
The Widget Builder
In the Widgets Library, you create a widget through the widget builder, which enables you to define and configure data, and preview how that widget appears. The widget builder allows you to create complex widgets which eliminates the need to write scripts or upload JSON files (although you have the option to do this). These complex widgets have the same capabilities as if you were creating a script-based widget.
You can create the following types of widgets through the widget builder:
Incidents: Widgets relating to incidents, such as active incidents by type, incidents by phase, late incidents, etc.
Indicators: Widgets relating to indicators, such as indicators by type, indicators activity, bad indicators, etc.
Script: Automation driven widget. Although you can create complex widgets using the widget builder, you can also create dynamic widgets using automation scripts, such as calculating the percentage of incidents that DBot closed. The automation script can also pull information from the Cortex XSOAR API.
Note
Before creating a script-based widget, you need to create a script in the Automation page and then select the script in the widget builder. The script must have the
widget
tag assigned, otherwise it does not appear when selecting the script in the widget builder.In the Widget builder, although you cannot manipulate the data (no data appears in the operations tab) you can define the arguments for the script and change the color, layout, legends, etc.
For automation script examples, see Create a Custom Widget Using an Automation Script.
War Room Entries: Widgets relating to the number of War Room entries, including number of entries according to owner, etc.
SOAR Metrics: Widgets relating to automations, playbooks, integrations, such as troubleshooting, how long it runs, number of runs for API, errors, etc.
Threat Intel Reports: Widgets relating to threat intel reports that have been created, such as reports by type, status, etc.
Upload: You can upload a JSON file to create a static widget, which displays relatively straightforward information, such as grouping incidents severity by type, active incidents by type, and so on.
Widget Creation
You can create the following types of widgets:
Widget | Description | |
---|---|---|
View data in a timer format. For example, mean time to assignment. In the Visuals tab, you can select the threshold color. | ||
View data in a number format. In the Visuals tab, you can select the threshold color. | ||
View data in a bar format. | ||
View data in a column format. | ||
View data in a pie format. | ||
View data in a line graph format. | ||
View data in a table format. Click the gear icon to edit columns. | ||
View data in a text format, which can be used as a text summary of the displayed data. You can use |
When you Create a Widget using the Widget Builder, you add the information according to the following tabs (you do not need to complete every tab, apart from Query):
Query: Queries a specific data type, defines the data query and the time frame to return. For example, to see all incidents that are not closed, not archived, and are not jobs, type the following information:
-status:closed and -status:archived and -category:job
Operations: The Operations tab enables you to do complex data manipulation, similar to scripting. You can configure the data according to groups and fields (including custom calculations on fields), create filters, transformers, etc. You can select how to calculate the data according to the following options:
Parameter
Description
Count
Counts the total value of the field. For example, to see the total number of incidents in your system. You can then group by type, severity, etc.
Average
Calculates the average value of the field. For example, to see the average number of incidents in your system over the selected time frame. You can then group by type, severity, etc.
Sum
Counts the value of the field according to a specific value. For example, when you define a metrics widget type, select the execution count, total duration, errors count, or create your own custom calculations.
Min
Calculates the minimum numeric value of the data. For example, you may want to see the minimum number of fetched events.
Max
Calculates the maximum numeric value of the data. For example, you may want to see the maximum number of fetched events.
When you select one of the widget data types, such as an incident type widget, relevant data for that widget is retrieved. For example, when selecting the incident type, in the Group by field all relevant data relating to incidents is retrieved, such as type, owner, created by, etc.
When selecting one of the options (apart from Count) you can choose one of the relevant fields from the dropdown list. If you want to create advanced calculations on fields, select Custom Calculations on fields.
Custom calculations on fields
Custom calculations on fields enable you to create more complex calculations on incident fields or between incident fields. When you select Custom Calculations on fields and start typing, the custom calculation modal suggests fields, based on the selected widget data type. For example, if you select an incident type widget, the custom calculation modal suggests incident fields to add. If you select an indicator type widget, the custom calculation modal suggests indicator fields to add. These fields are automatically validated.
Note
Instead of using the modal suggestions, you can add your own custom fields (provided they exist) according to the widget data type, by adding the CLI name. These fields are not validated.
You can add mathematical operators (such as
+, -, /, *
) between fields. Variables using{}
are also supported.For example, to see the average time that incidents are late, type the following:
{now}-remediationsla.dueDate
To calculate the average time between detection and remediation for phishing incidents (in the phishing generic playbook we set the time detection and remediation SLA timers), type the following:
remidationsla.startDate-detectionsla.startDate
To see remediations (less 10 minutes), type
remdiationsla.dueDate-10
.Grouping
You can further manipulate the data according to one or two groups (two groups are useful for vertical bars and line charts). Within each group, you can group by a bucket. For example, you have two teams - Team A and Team B, each one is made up with different team members. You only want to see Team A and Team B and not the individual team members.
Limiting the number of results
You can limit the amount of results to return, view the most, or least popular, and for some fields, select the time format. For example you may want to see the top 10 most popular active incidents by month.
Visuals: You can change how the widget appears, by adding names for vertical and horizontal axis, define the format, show the legend, reference line, etc.
Change Color of Items in Widgets: You can change the color of items (such as indicator types, incident types, etc.) in some widgets, depending on the widget type and the chart/graph type. When editing a widget, click on the item within the legend in the preview window on the right. The Edit color option appears and you can select the color for the item.
If you edit the color after a widget has been added to a dashboard or report, the change only applies to the widget within that dashboard or report. If you edit the widget directly in the Widgets Library before adding it to a dashboard or report, the change is applied every time you add the widget to a dashboard or report. Changes to an item within a widget only apply within that widget. For example, changing the color for the
Phishing
incident type within the Active Incidents widget only applies to Active Incidents, and not other widgets that contain incident types.