Create a widget using the widget builder - Administrator Guide - 8.5 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR On-prem Documentation

Product
Cortex XSOAR
Version
8.5
Creation date
2024-03-10
Last date published
2024-11-28
Category
Administrator Guide
Solution
On-prem
Abstract

Create a widget in the Widgets Library in and then add the widget to a dashboard or report.

In the Widgets Library, you create a widget using 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, eliminating 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.

In the Widgets Library of the report or dashboard you are creating or editing, click new-widget.png and select the widget type as follows.

Widget type

Description

Incidents

Use incident data to create widgets related to incidents, for example timestamps, duration, incident types, and any incident field.

Indicators

Use indicator data to create widgets related to indicators, for example timestamps, indicator types, and any indicator field.

SOAR Metrics

Use SOAR metrics data to create widgets related to scripts, playbooks, and integrations, for example executions, durations, and errors.

Tasks

Use tasks data to create widgets related to investigation tasks, for example assignee, playbook name, and duration (manual or automated).

Note

When creating a widget based on the results of an investigation task, 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

Use a script to create a 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, you cannot manipulate data (no data appears in the Operations tab). However, you can define script arguments and change the color, layout, and legends.

For more information, see Create a custom widget using a script.

Threat Intel Reports

Use threat intel data to create widgets related to threat intel reports that have been created, for example reports by type and status.

Upload

Upload a JSON file to create a static widget which displays basic information, such as grouping incidents severity by type and active incidents by type.

In the Query step, set the following information:

Parameter

Description

Widget display format

Select one of the widget format icons. You can see a preview of how the widget appears.

Widget format

Description

widget-timer.png

View data in a timer format. For example, mean time to assignment. In the Visuals tab, you can select the threshold color.

widget_number.png

View data in a number format. In the Visuals tab, you can select the threshold color.

widget_bar.png

View data in a bar format.

widget_barchart.png

View data in a column format.

widget_pie.png

View data in a pie format.

widget_graph.png

View data in a line graph format.

widget_table.png

View data in a table format. Click the gear icon to edit columns.

widget_text.png

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.

Data source

Select the source data to query.

Cortex XSOAR retrieves data relevant for that data source. For example, for Incidents, in the Group by field all data relating to incidents is retrieved, such as type, owner, and created by.

Widget data source

Description

Incidents

Use incident data to create widgets related to incidents, for example timestamps, duration, incident types, and any incident field.

Indicators

Use indicator data to create widgets related to indicators, for example timestamps, indicator types, and any indicator field.

SOAR Metrics

Use SOAR metrics data to create widgets related to scripts, playbooks, and integrations, for example executions, durations, and errors.

War Room Entries

Use War Room entry data to create widgets, for example number of entries according to owner.

Tasks

Use tasks data to create widgets related to investigation tasks, for example assignee, playbook name, and duration (manual or automated).

Note

When creating a widget based on the results of an investigation task, 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

Use a script to create a 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, you cannot manipulate data (no data appears in the Operations tab). However, you can define script arguments and change the color, layout, and legends.

For more information, see Create a custom widget using a script.

Threat Intel Reports

Use threat intel data to create widgets related to threat intel reports that have been created, for example reports by type and status.

Query

Queries data in the Lucene query syntax form relating to the data source.

For example when the data source is incidents and the query is: -status:closed and owner:"", it queries all incidents that are not closed which do not have an owner.

Or to see all incidents that are not closed, not archived, and are not jobs, use the query: -status:closed and -status:archived and -category:job.

Date range

The time frame to retrieve data.

Widget name

Type a meaningful name for the widget.

This step enables data manipulation, similar to scripting. You can configure the data according to groups and fields (including custom calculations on fields).

  1. (Not relevant for tables or text) Click the Operations step, and in the Values section select one of the following calculations to perform on the data (not relevant for Script and War Room Entries data sources).

    Calculation

    Description

    Count

    Counts the total value of the field. For example, display the total number of incidents in your system. You can then group by type and severity.

    Average

    Calculates the average value of the field. For example, display the average number of incidents in your system over the selected time frame. You can then group by type and severity.

    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.

  2. (Not relevant for Count) Select one of the fields from the dropdown or create your own custom calculations by selecting Custom calculations on fields.

  3. If adding custom calculations, type the calculation as required.

    The custom calculation modal suggests incident fields based on the widget data type, which are automatically validated. You can add your own fields (provided these fields exist), according to the widget data type, by using 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 {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 remidationsla.startDate-detectionsla.startDate.

    • To see remediations (less 10 minutes), type remdiationsla.dueDate-10.

  4. In the Axis and grouping section Group by field, from the dropdown, select the group you want to add.

    By default, the results are limited to the top 10 most popular results. If you want to change the top most popular to the least popular, change the number, or you want to see the remaining results that are not covered in one group (the Show ‘Others’ checkbox), click the edit button and update as required.

    If you want to add a custom field, ensure the Make data available for search incident type field is checked when editing or creating a new field.

    Example 21. Limit 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.

    widget-pop.png

  5. (Optional) Define custom groups (for example, define specific owners in the owner group).

    1. Click Custom ‘Group by’.

    2. In the Create Custom groups window, click Equals (String) to change the operator.

    3. Select a value from the dropdown.

    4. Change the name as required.

    5. If you want to create a second group, click Add custom group.

    6. If you want to add a group for all other values that have not been defined, click the Create and display a group for all remaining values checkbox.

    Example 22. Group data into two teams

    You can manipulate 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, for 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.

    widget-group.png

  6. In the Second group by field, add the group as required. For example, to see data filtered by owner and severity, select Group By Owner and Second Group by Severity.

  1. Click the Visuals step and define how the widget appears.

    Parameter

    Description

    Axis name

    The name of the axis for both horizontal and vertical.

    Format

    Select the format of the table for both horizontal and vertical axis. For example, hours, minutes, days, weeks, etc.

    Reference Line

    Whether you want a line showing the average, minimum, maximum, or custom line.

    Show Legend

    Whether you want to see the legend in your widget.

    Show also percentage

    Displays the percentage when selecting a pie chart.

    Show values on the graph

    Add the values on the chart widget.

    Display trend

    Compares dates for a particular period in a number widget. For example, this week vs. last week, this year vs. last year, and so on. To change the comparison period, in the Time frame field from the dropdown, select the relevant date.

    Widget color threshold

    Select the Widget color threshold in a number or duration widget to highlight the threshold data and define the threshold by selecting the Widget color threshold checkbox. For example, if less than 150 red, 100 yellow, 50 green. To add more thresholds, click Add new threshold. You can change the colors as required.

  2. To change the color, in the preview section, hover next to the legend, click the ellipsis and then click Edit color.

  1. Click Save.

    The widget is added to the widgets library.

  2. Add the widget to the dashboard or report.

    When you add the widget, it automatically uses the date range of the dashboard or report. You can change it by clicking the settings icon and selecting Use widget’s date range. To revert, click the settings icon again and select Use dashboard’s date range.