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.
Cortex XSOAR comes with a number of out-of-the-box system widgets, such as Late Incidents, Saved by Dbot. You can edit these widgets when creating or editing a dashboard or report.
Note
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 and 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 1 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.
SOAR Metrics: Widgets relating to scripts, playbooks, integrations, such as troubleshooting, how long it runs, number of runs for API, errors, etc.
Tasks: Widgets relating to investigation tasks, including assignee, playbook name, duration, manual, or automated.
Note
If you want to create a widget based on the results of an investigation task, note that only the following task types are supported for widget aggregation:
Manual tasks
Tasks that have an assignee
Tasks that have a due date
Tasks that are in an error state
Oversized tasks
Scripts: Script driven widget. Although you can create complex widgets using the widget builder, you can also create dynamic widgets using scripts, such as calculating the percentage of incidents that DBot closed. The 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 Scripts 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 script examples, see Create a Custom Widget Using an Automation Script.
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 basic 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 {0} to display a query value and {date} to display the date. Markdown is supported. |
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 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.