Script Based Widgets Using Automation Scripts Examples - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Product
Cortex XSOAR
Version
8
Creation date
2023-11-02
Last date published
2024-02-21
Category
Administrator Guide
Abstract

Create script based widgets based on automation scripts for reports and dashboards in Cortex XSOAR.

Use the following arguments/scripts to create a widget. After creating a script, Create a Widget Using the Widget Builder.

Arguments Used in a Script

If you want to add a time stamp or a use a search query, add the following arguments to a script.

Argument

Description

demisto.args()[‘from’]

The start date of the time-stamp date range of the widget.

demisto.args()[‘to’]

The end date of the time-stamp date range of the widget.

demisto.args()['searchQuery']

The search query entered into the search bar at the top of the dashboard.

Text

In this example, create a script that queries and returns current on-line users, and displays the data in a markdown table.

In the script, type one of the following return values:

JavaScript

return executeCommand("getUsers", {online: true})[0].HumanReadable;

Python

demisto.results(demisto.executeCommand("getUsers", { "online": True })[0]["HumanReadable"])

When creating or editing the widget in Cortex XSOAR, to add a page break, type /pagebreak in the text box. When you generate a report, the widgets that follow the page break are on a separate page.

quick-definitions-pagebreak-2.png

In the dashboard, the following widget displays the on-line users:

onelineusers_widget.png

Note

(Multi-tenant) Script-based text widgets are not supported in the Main Account.

Number

This example shows how to create a single item widget with the percentage of incidents that DBot closed.

In the script, type one of the following:

JavaScript

   var res = executeCommand("getIncidents", {
'query': 'status:closed and investigation.users:""', 
'fromdate': args.from, 
'todate': args.to,
'size': 0 
});
var closedByDbot = res[0].Contents.total;

res = executeCommand("getIncidents", {
  'status': 'closed',
  'fromdate': args.from, 
  'todate': args.to, 
  'size': 0 });
var overallClosed = res[0].Contents.total;

var result = Math.round(closedByDbot * 100 / overallClosed);
return isNaN(result) ? 0 : result;

Python

res = demisto.executeCommand("getIncidents", {
    "query": "status:closed and investigation.users:\"\"",
    "fromdate": demisto.args()["from"],
    "todate": demisto.args()["to"],
    "size": 0
})
closedByDbot = res[0]["Contents"]["total"]

res = demisto.executeCommand("getIncidents", {
    "status": "closed",
    "fromdate": demisto.args()["from"],
    "todate": demisto.args()["to"],
    "size": 0
})
overallClosed = res[0]["Contents"]["total"]
if overallClosed == 0:
    demisto.results(0)
else:
    result = round(closedByDbot * 100 / overallClosed)
    demisto.results(result)
Duration

In this example, create a script that queries and returns a time duration (specified in seconds), and displays the data as a countdown clock. If using a JSON file, you must set widgetType to duration.

In the script, type one of the following return values:

JavaScript

return JSON.stringify([{ name: "", data: [120] }]);

Python

demisto.results('[{"name": "", "data": [120]}]')

The return type should be a string (any name) and an integer. The time is displayed in seconds.

After you have uploaded the script and created the widget, you can add the widget to the dashboard or report. The duration-2.jpg widget displays the time duration:

widget-time-example.jpg
Chart

A valid result for a chart widget is a list of groups. Each group points to a single entity, for example, in bar charts each group is a bar. A group consists of the following:

  • Name - A string.

  • Data - An array of integers.

  • Color - A string representing a color that will be used as a default color for that group. It can be the name of the color, a hexadecimal representation of the color, or an rgb color value (optional).

    Note

    A widget legend color will override a group color if it exists.

  • Groups - A nested list of groups (optional).

In this example, we show how to create a script that will query and return the trend between two sums in a pie chart.

  • Pie

  • Line

  • Bar

  • Column

Simple pie/chart

In the script, type the following return value:

JavaScript

									var data = [
    {name: "2018-04-12", data: [10], color: "blue"},
    {name: "2018-04-10", data: [3], color: "#029be5"},
    {name: "2018-04-17", data: [1], color: "rgb(174, 20, 87)"},
    {name: "2018-04-16", data: [34], color: "grey"},
    {name: "2018-04-15", data: [17], color: "purple"}
];
return JSON.stringify(data);			

Python

data = [
    {"name": "2018-04-12", "data": [10], "color": "blue"},
    {"name": "2018-04-10", "data": [3], "color": "#029be5"},
    {"name": "2018-04-17", "data": [1], "color": "rgb(174, 20, 87)"},
    {"name": "2018-04-16", "data": [34], "color": "grey"},
    {"name": "2018-04-15", "data": [17], "color": "purple"}
]
demisto.results(json.dumps(data))

After you have uploaded the script and created the widget you can add the widget to a dashboard or report.

Two group chart

JavaScript

var data = [
    {name: "2018-04-12", data: [10], groups: [{name: "Unclassified", data: [10] }]},
    {name: "2018-04-10", data: [3], groups: [{name: "Unclassified", data: [2] }, {name: "Access", data: [1] }]},
    {name: "2018-04-17", data: [1], groups: [{name: "Unclassified", data: [1] }]},
    {name: "2018-04-16", data: [34], groups: [{name: "Unclassified", data: [18] }, {name: "Phishing", data: [14] }]},
    {name: "2018-04-15", data: [17], groups: [{name: "Access", data: [17] }]}
];
return JSON.stringify(data);

Python

data = [
    {"name": "2018-04-12", "data": [10], "groups": [{"name": "Unclassified", "data": [10] }]},
    {"name": "2018-04-10", "data": [3], "groups": [{"name": "Unclassified", "data": [2] }, {"name": "Access", "data": [1] }]},
    {"name": "2018-04-17", "data": [1], "groups": [{"name": "Unclassified", "data": [1] }]},
    {"name": "2018-04-16", "data": [34], "groups": [{"name": "Unclassified", "data": [18] }, {"name": "Phishing", "data": [14] }]},
    {"name": "2018-04-15", "data": [17], "groups": [{"name": "Access", "data": [17] }]}
]
demisto.results(json.dumps(data))
Trend

In this example, create a script that queries and returns the trend between two sums.

In the script, type one of the following return values:

JavaScript

return JSON.stringify({currSum: 48, prevSum: 32});

Python

demisto.results({ "currSum": 48, "prevSum": 32 })

The return displays an object which compares the current sum with the previous sum.

Table or List

In this example, you need to create a script that queries and returns employee information in a table. For Table or List, if creating a JSON file, set the widgetType to table or list. When using lists, a maximum of two columns displays, the rest are ignored (do not display).

In the script, type one of the following return values:

JavaScript

return JSON.stringify({total: 3, data:[
  {Employee: 'David D', Phone: '+14081234567', Email:
  'David@org.com'},
  {Employee: 'James J', Phone: '+14087654321', Email:
  'James@org.com'}, 
  {Employee: 'Alex A', Phone: '+14087777777', Email:
  'Alex@org.com'}
  ]});

Python

demisto.results({ "total": 3, "data": [{"Employee": "David D",
 "Phone": "+14081234567", "Email": "David@org.com"}, {"Employee":
 "James J", "Phone": "+14087654321", "Email": "James@org.com"}, 
{"Employee": "Alex A", "Phone": "+14087777777", "Email":
 "Alex@org.com"}]})

After you have uploaded the script and created a widget you can add the widget to a dashboard or report. The following widget displays the employee information:

widget_example_employee.png
Filter Data for all Widgets (Pivoting)
Example: Display Filtered Incident and Indicator Data in a Widget with a Bar Graph

In this example, you create a filter according to type (phishing, access and IP) and then pivot to the relevant incident/indicators page. You need to add the following to the JSON or python script.

  • dataType: Pivots to the relevant page, such as Incidents page.

  • query: Filters according to the value in the relevant page. For example, for phishing, if you define ‘type:Phishing’ and the dataType:incidents, you are taken to the Incident page with the ‘type:Phishing’ filter.

  • pivot: Filters the dashboard according to data set. For example, pivot: “type:Phishing” enables you to filter data that relates to phishing in the dashboard.

In the script, type one of the following return values:

JavaScript

return JSON.stringify([{name: "Phishing", dataType:"incidents", query:"type:Phishing", data: [50],  pivot: "type:Phishing"},
{name: "Access", dataType:"incidents", query:"type:Access", data: [50], pivot: "type:Access"},
{name: "IP", data: [50], dataType: "indicators", query:"type:IP", pivot:"type:IP"}]);

Python

data = [
    {"name": "Phishing", "data": [50], "dataType": "incidents", "Query": "type:Phishing",  "pivot": "type:Phishing"},
    {"name": "Access", "data": [50], "dataType": "incidents", "query": "type:Access",  "pivot": "type:"Access"},
    {"name": "IP", "data": [50], "dataType": "indicators", "query": "type:"IP", "pivot": "type:IP"}
]
demisto.results(json.dumps(data))

After you upload the script and created a widget, add the widget to a dashboard or report page.

widget-customfilter-2.png
Example: Display Filtered Incident and Indicator Data in a Widget with a Line Graph

In this example, you create a filter according to type (phishing, access and IP) and then pivot to the relevant incident/indicators page. You need to add the following to the JSON or python automation script.

JavaScript

return JSON.stringify([
    {
    "name": "Jan 1, 2024",
    "data": [6],
    "groups": [
      { "name": "Phishing", "data": [1], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [2], "pivot": "type:Acce", "query": "type:Access" },
      { "name": "IP", "data": [3], "pivot": "type:IP", "query": "type:IP" }
    ]
  },
  {
    "name": "Jan 2, 2024",
    "data": [7],
    "groups": [
      { "name": "Phishing", "data": [2], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [1], "pivot": "type:Access", "query": "type:Access" },
      { "name": "IP", "data": [4], "pivot": "type:IP", "query": "type:IP" }
    ]
  },
  {
    "name": "Jan 3, 2024",
    "data": [8],
    "groups": [
      { "name": "Phishing", "data": [3], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [4], "pivot": "type:Access", "query": "type:Access" },
      { "name": "IP", "data": [1], "pivot": "type:IP", "query": "type:IP" }
    ]
  }
]);

Python

data = [
  {
    "name": "Jan 1, 2024",
    "data": [6],
    "groups": [
      { "name": "Phishing", "data": [1], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [2], "pivot": "type:Acce", "query": "type:Access" },
      { "name": "IP", "data": [3], "pivot": "type:IP", "query": "type:IP" }
    ]
  },
  {
    "name": "Jan 2, 2024",
    "data": [7],
    "groups": [
      { "name": "Phishing", "data": [2], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [1], "pivot": "type:Access", "query": "type:Access" },
      { "name": "IP", "data": [4], "pivot": "type:IP", "query": "type:IP" }
    ]
  },
  {
    "name": "Jan 3, 2024",
    "data": [8],
    "groups": [
      { "name": "Phishing", "data": [3], "pivot": "type:Phishing", "query": "type:Phishing" },
      { "name": "Access", "data": [4], "pivot": "type:Access", "query": "type:Access" },
      { "name": "IP", "data": [1], "pivot": "type:IP", "query": "type:IP" }
    ]
  }
]

demisto.results(json.dumps(data));

After you upload the script and create a widget, add the widget to a dashboard or report page.

widget-pivot-line-graph.png