Incident layout customization

Customize incident layouts in Cortex XSOAR 8 SaaS.

Each incident type has a unique set of data relevant to that specific incident type, including layouts. It is important to display the most appropriate data for users. Each out-of-the-box incident comes with a layout. You can customize almost every aspect of the layout, including which tabs appear, in which order they appear, who has permission to view the tabs, what information appears, and how it is displayed.

It's important to build or customize the layout so that you see the information that is relevant to the incident type. For example, in a phishing incident, you may want to see email headers, but not in an access incident. While some information might be appropriate for multiple incident types, its location in one incident may require more prominence than in another incident.

You can see which incident type uses the incident layout in the Types tab under Settings & Info → Settings → Object Setup → Incidents. The incident layout name appears in the Layout column. You can edit the layouts in the Layouts tab.

You can customize the display information including fields for existing incidents, by modifying the sections and fields for the following views:

Section	Description
Incident Summary	The Incident Summary tab displays the information necessary to investigate an incident. You can customize almost every aspect of the layout, including which tabs appear, the order they appear, and who has permission. In each field or tab, you can add filters by clicking on the eye icon, which enables you to add conditions that show specific fields or tabs. For example, if an analyst decides that a Cortex XDR Malware incident is a Ransomware subtype, they may only want fields to appear that show data about the encryption method and not to show information if the Malware subtype is adware. You may also want to limit specific tabs to certain scenarios. For example, if a user clicks a phishing link, the new tab can contain relevant fields and action buttons for this scenario. You can also add dynamic fields, such as a graph of several bad indicators, their source, and severity. For more information, see Create dynamic fields. Also, you can use queries to filter the information in the dynamic section to suit your exact needs.
New/Edit form	Add, edit, and delete fields and buttons to be displayed when creating or editing an incident.
Close Form	Add, edit, or delete sections, fields, and filters, when closing an incident.
Incident Quick View	Add, edit, and delete sections, fields, and filters in the Incident Quick view section in the incident.

Note

There are several out-of-the-box layout sections and fields that you cannot remove, but you can rearrange them in the layout and modify their queries and filters. These layouts need to be duplicated or detached to make changes.

We recommend copying an existing out-of-the-box incident layout so you don't miss any important information.

Create an incident layout

1. Go to Settings & Info → Settings → Object Setup → Incidents → Layouts.

   You can customize the following tabs:

   • Incident Summary
   • "New/"Edit" Form
   • "Close" Form
   • Incident Quick View
2. Add a meaningful name for the layout.
3. Customize the tabs by clicking the settings wheel icon and then doing the following:

   Note

   You can click and drag a tab to reorder the tabs.

   Action	Description
   Rename	You can also edit a tab’s name by clicking the tab.
   Duplicate	Copies the existing tab.
   Delete	Deletes the tab.
   Show empty fields	The setting that you configure in the layout becomes the default value seen in the report for the specific tab, which can then be overridden. You can also set a global default value using the UI.summary.page.hide.empty.fields server configuration, which can also be overridden for a specific tab.
   Hide tab	Hides the tab. Rather than deleting the tab, you may want to use the tab again for future use.
   Format for exporting	Build your layout based on A4 proportions to match the format used for exporting. Selecting this option hides the tab by default, but the tab will remain available for export.
   Viewing Permissions	Select which roles can view the tabs.
   Display Filter	Add or view a filter applied to the tab. If the filters apply, the specific fields or tabs are shown in the layout. If the mandatory field is not shown in the layout, the user is not obliged to complete it.

4. Do the following:

   • Drag and drop the required sections, fields, buttons, and tabs.
   • Customize sections and create buttons.
   • Add any required filters.
   • Create new tabs
5. In the "New"/"Edit" Form and "Close" Form tabs, drag and drop the required fields and buttons.

   You can also edit the Basic Information and the Custom Field sections.
6. Repeat step 3 for the Incident Quick View tab.
7. Save the layout, and add it to the incident type.

   Note

   If the incident type is attached, you need to detach or duplicate it, if you want to add the layout.
8. Create or ingest an incident to test the new layout and verify fields are populated.
9. (Optional) For a customized layout (duplicate or new layout), you can contribute it to the Marketplace.

   1. In the Layouts page, right-click the new layout and select Contribute.
   2. In the dialog box, select either Save and submit your contribution or Save and download your contribution for later use, which you can view in the Contributions tab in the Marketplace.

      If you select Save and submit your contribution your layout is validated and then you are prompted to submit to review. You can also view your contribution in the Marketplace.

Edit an incident layout

1. Go to Settings & Info → Settings → Object Setup → Incidents → Layouts.
2. Click the layout name you want to edit.

   You can see with the current layout, which is populated with demo data so you can see how the fields fit.
3. If editing a layout that has been installed from a content pack (the layout shows a locked icon), do one of the following:

   • Duplicate an incident layout

     To add the layout to the incident type, you need to detach the incident type and then add the layout. To duplicate an incident layout, right-click the layout name in the layouts table, and select Duplicate.
   • Detach the layout.

     When detached, the layout does not receive content pack updates until you reattach it. You do not need to edit the incident type, as the layout name remains the same.

     Tip

     While a layout is detached, it does not receive content pack updates. If you detach a layout and make changes, any changes made while it was detached are overwritten by the default values from the content pack. If you want to keep the changes and protect your changes from content pack upgrades, duplicate the incident type before reattaching the original.

     To detach or reattach an incident layout, right-click the layout name in the layouts table, and select Detach or Attach.
4. Add sections, buttons, and fields, as required.

Customize sections

1. Create or edit a layout.
2. From the Sections tab in the Library, drag and drop the following sections:

   Section	Description
   New Section	After creating a new section, click the Incident type Fields tab and drag and drop the fields as required.
   Cortex XSOAR out-of-the-box sections	Out-of-the-box sections such as attachments and evidence.
   General Purpose Dynamic Section	You can add a script to the incident layout. For example, assign a script that calculates the total number of entries that exist for an incident, which dynamically updates when new entries are added to the incident.

   Note

   To remove or duplicate a section, select the section, click , and then select Duplicate or Remove.
3. Define section properties by clicking and then Edit section settings.

   Tip

   Limit the number of incident fields to 50 in each section. You can create additional sections as needed.

   You can determine how a section in the layout appears in the layout. For example, you may want a section header, or configure the fields to appear in rows or as cards. If some of the field values will be very long, use rows instead of cards. If the field values are short, you might want to use cards so you can fit more fields into a section.

   To add a long description in the Description field, click Scrollable description to add a scrollbar to enable the displayed information to grow to fit the content.
4. If adding the Malicious or Suspicious Indicators section, you can change the information that appears, by editing the Query.

   For example, to see all indicators of type IP and with a reputation of Bad that were found by a specific source since January 2nd 2022, enter Type:IP and reputation:Bad and firstseenbysource:>="2021-01-02T00:00:00 +0200"
5. Drag and drop fields, and add any filters as required.
6. If relevant, create a new tab and repeat the steps as required.

Add a script to the layout

You can add script-based content to the incident layout by adding the General Purpose Dynamic Section in the incident layout builder. The General Purpose Dynamic Section enables you to configure a section in the incident layout from a script. The script can return a simple text, markdown, or HTML, the results of which appear in the General Purpose Dynamic Section.

You can add any required information from a script. For example, you can assign a script that calculates the total number of entries for an incident, which dynamically updates when new entries are added to an incident. You can add a custom widget to the incident page and add note information using a script.

The following are examples of values that can be returned from the General Purpose Dynamic Section script:

Text example

return_results(<TEXT>)

Markdown example

return_results({
    'ContentsFormat': EntryFormat.MARKDOWN,
    'Type': EntryType.NOTE,
    'Contents': <MARKDOWN_DATA>
})

HTML example

return_results({
    'ContentsFormat': EntryFormat.HTML,
    'Type': EntryType.NOTE,
    'Contents': <HTML_DATA>
})

For the EntryFormat values see EntryFormat in Common Server Python functions.

How to add a script to a layout

Before you begin, you need to create a script.

1. Create a script.

   For examples of script-based widgets for layouts, see Examples of using scripts in incident layouts

   Add the dynamic-section tag.
2. Create or edit an incident layout.
3. Drag and drop the General Purpose Dynamic Section into the layout area you want to appear.
4. Select the General Purpose Dynamic Section, click and then click Edit section settings.
5. In the Name and Description fields, add a meaningful name and a description for the dynamic section that explains what the script displays.
6. In the Automation script field, from the dropdown list, select the script that returns data for the dynamic section.

   Note

   Only scripts to which you have added the dynamic-section tag appear in the dropdown list.
7. Save the section.

Create custom buttons

You can add existing buttons or create buttons and then drag and drop them in the layout.

To add a custom button, create a script and then add the new button to the layout and select a script. These buttons can simplify and assist an analyst in carrying out various tasks. For example, add buttons for an analyst to self-assign an incident, link or unlink an incident, close an incident as a duplicate, or generate a summary report.

For fields (script arguments) that are optional, you can define whether to show them to analysts when they click on buttons. To expose an optional field, select the Ask User checkbox next to the script arguments in the button settings page.

In the following example, add a button to the layout, which self-assigns an incident for an analyst. The Common Scripts content pack includes an AssignToMeButton Script.

Note

When creating a script for use in an incident layout, the incident-action-button tag must be assigned for the script to be available for custom buttons.

The script that runs when an action button is clicked accepts only mandatory arguments through the pop-up window and does not provide an option for any non-mandatory arguments to be filled in when the button is clicked. It is recommended to use a wrapper script to collect and validate arguments in scenarios where there can be a combination of mandatory and non-mandatory arguments for a button.

In the following example, create a button to self-assign an incident for an analyst, and add it to a layout.

1. Create or edit a layout.
2. Create a new section.
3. In the Fields and Buttons tab, drag and drop the New Button into the relevant section.
4. Click to configure.
5. In the Button Display Name, enter Assign to Me.
6. Select a color if required.
7. In the Button Script field, add the AssignToMeButton script.
8. Save the Button settings and then save the layout.

   Note

   The Case Management - Generic content pack includes several buttons to use in a layout, such as Assign to Me, Close as Duplicate, and Link incidents. You can also see useful case management incident layouts. For more information, see Case Management - Generic content pack.

Add the layout to an incident type

1. Go to Settings & Info → Settings → Object Setup → Incidents → Types.
2. Select the incident type and click Edit.
3. In the Layout field, from the dropdown list, add the customized layout.
4. (Optional) For a customized layout, you can contribute it to the Marketplace.

   1. In the Layouts page, select the new layout and then click Contribute to Marketplace.
   2. In the dialog box select either Save and submit your contribution or Save and download your contribution for later use, which you can view in the Contributions tab in Marketplace.

      If you select Save and submit your contribution, your layout is validated and you are prompted to submit to review. You can also view your contribution in Marketplace.

Add incident access control fields to the layout

In any SOC team, there are various roles and responsibilities. For example, you may have specific teams to deal with threats, such as threat intelligence researchers, security analysts (Tier 1), senior analysts (Tier 2), SOC leads, SOC managers, and SIEM engineers. You have various options to limit access to incidents and investigations.

• Exclude access to incident actions and investigations according to roles using role-based permissions. For example, you may want to limit the ability to change the incident status, or manage the Work plan. For more information, see Role-based permissions in Cortex XSOAR.
• Restrict an investigation according to team members. In an investigation, the owner of the incident can restrict the incident to team members only.

  Analysts can select Restrict incident (under Actions) to restrict an incident.

  Note

  If using a script, use the restrictInvestigation command. You need to specify the incident ID of the incident and set the Restrict argument to True to restrict the incident or set the Restrict argument to False to remove restriction from the incident.
• Limit access to investigations by doing the following:

  • Limit investigations according to specific user roles

    You can add the Roles field to the layout, which enables you to restrict access to all roles other than those you have specifically added. For example, after an investigation is closed, add administrators or those with specialty roles, so only they can reopen or link incidents. The added roles have read and write permission, but all other roles do not have access (unless you have added them in the read-only field).

    Note

    • You can also run the /incident_set roles=``<name of role> or !setIncident roles =``<name of role> in the CLI, playbook, or script to set the role.
    • If you add a role, but the incident has been restricted to team members, and the user is not a team member, the user cannot access the incident regardless of the role. For example, if you restrict the incident to User A and User B team members who are Tier 1 analysts but then try to add Tier 2 analysts (none of whom are team members) to the list of roles, a Tier 2 analyst cannot access the incident.
  • Give read-only access to certain user roles

    You add the XSOAR Read Only Roles field to the layout, which restricts access to the incident. When granting read-only access, the user can view the incident but not edit. For example, when an incident is in triage (phase 1), you may want all Tier-2 analysts to have read-only access, so that Tier-1 can edit the incident. When the phase changes to phase 2, Tier-1 has read-only access.

    Adding a team member overrides the XSOAR Read-Only Roles field, so if you add User A, (Tier 1) as a team member, even if you assign Tier-1 as a read-only role, the user still has Read/Write access. You need to remove the user as a Team Member.

    Although an analyst can change the XSOAR Read-Only field manually, you can automate the process by creating a custom incident field using Incident Field Trigger Scripts, or create a script and add a new field button.

    Note

    You can also run the !setIncident xsoarReadOnlyRoles=``<name of role> in the CLI, playbook, or script to set the user role.

    If you assign a role (read and write permission) and assign the same role as read-only, the user still has read/write permission. You need to remove the assigned role. If you restrict the incident, the read-only role does not override the restriction. In other words, team members' permission takes precedence.

Examples of using scripts in incident layouts

The following are examples of scripts that are supported in incident layouts:

Charts

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).
• Groups: A nested list of groups (optional).

Horizontal bar

In this example, create a script in Python that displays a horizontal bar of the indicators by severity.

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

vertical-bar-graph.png

Vertical bar

In this example, create a script in Python that displays a vertical bar of the indicators by severity.

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

horizontal-bar-graph3.png

Stacked bar

In this example, create a script in Python that displays a stacked bar showing the successes and failures on specific dates.

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

horizontal-bar-graph2.png

Line chart

In this example, we create a JavaScript that displays how many GitHub issues were created each week for Content, Documentation, and Platform in a line chart.

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

widget-line.png

Pie

In this example, create a script in Python that queries and returns a pie chart.

data = {
    "Type": 17,
    "ContentsFormat": "pie",
    "Contents": {
      "stats": [
        {
          "data": [
            1
          ],
          "groups": None,
          "name": "high",
          "label": "incident.severity.high",
          "color": "rgb(255, 23, 68)"
        },
        {
          "data": [
            1
          ],
          "groups": None,
          "name": "medium",
          "label": "incident.severity.medium",
          "color": "rgb(255, 144, 0)"
        },
        {
          "data": [
            2
          ],
          "groups": None,
          "name": "low",
          "label": "incident.severity.low",
          "color": "rgb(0, 205, 51)"
        },
        {
          "data": [
            8
          ],
          "groups": None,
          "name": "unknown",
          "label": "incident.severity.unknown",
          "color": "rgb(197, 197, 197)"
        }
      ],
      "params": {
          "layout": "horizontal"
      }
    }
  }

  demisto.results(data)

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays indicator severity as a pie chart:

pie-chart.png

Duration

In this example, create a script in Python that queries and returns a time duration (specified in seconds), and displays the data as a countdown clock.

 data = {
    "Type": 17,
    "ContentsFormat": "duration",
    "Contents": {
      "stats": 60 * (30 + 10 * 60 + 3 * 60 * 24),
      "params": {
          "layout": "horizontal",
          "name": "Lala",
          "sign": "@",
          "colors": {
            "items": {
              "#00CD33": {
                "value": 10
              },
              "#FAC100": {
                "value": 20
              },
              "green": {
                "value": 40
              }
            }
          },
        "type": "above"
      }
    }
  }

  demisto.results(data)

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays the time duration:

duration.png

Number

This example shows how to create a single item widget that displays a number.

 data = {
    "Type": 17,
    "ContentsFormat": "number",
    "Contents": {
      "stats": 53,
      "params": {
          "layout": "horizontal",
          "name": "Lala",
          "sign": "@",
          "colors": {
            "items": {
              "#00CD33": {
                "value": 10
              },
              "#FAC100": {
                "value": 20
              },
              "green": {
                "value": 40
              }
            }
          },
        "type": "above"
      }
    }
  }

  demisto.results(data)

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

number.png

Number Trend

This example shows how to create a single-item widget that displays a number trend.

data = {
    "Type": 17,
    "ContentsFormat": "number",
    "Contents": {
      "stats": { "prevSum": 53, "currSum": 60 },
      "params": {
          "layout": "horizontal",
          "name": "Lala",
          "sign": "@",
          "colors": {
            "items": {
              "#00CD33": {
                "value": 10
              },
              "#FAC100": {
                "value": 20
              },
              "green": {
                "value": 40
              }
            }
          },
        "type": "above"
      }
    }
  }

  demisto.results(data)

After you have uploaded the script and created the widget, you can add the widget to an incident layout. The following widget displays:

number-trend.png

Add note information

This example shows how to add note information to an incident layout using a script through the API.

1. Install the Cortex REST API content pack and add a Core REST API instance.
2. Go to the Scripts page and add the following script:

   commonfields:
     id: ShowLastNoteUserAndDate
     version: -1
   name: ShowLastNoteUserAndDate
   script: |2
   
     function getLastNote(incidentID) {
         var body = {pageSize:1,categories:['notes']};
         var res = executeCommand('demisto-api-post', {uri:'/investigation/' + incidentID, body: body});
         if (isError(res[0])) {
             throw 'demisto-api-post failed for incidnet #'+incidentID+'\nbody is ' + JSON.stringify(body) + '\n' + JSON.stringify(res);
         }
         if (!res[0].Contents.response.entries) {
             return null;
         }
         var notes = res[0].Contents.response.entries;
         var lastNote = notes[notes.length-1];
         return lastNote;
     }
   
     lastNote = getLastNote(incidents[0].id);
   
     if (lastNote) {
         md = `#### Update by ${lastNote.user} on ${lastNote.modified.split('T')[0]}\n`;
         md += `\n---\n`;
         md += lastNote.contents + '\n';
   
         return { ContentsFormat: formats.markdown, Type: entryTypes.note, Contents: md } ;
     } else {
         return 'N/A';
     }
   type: javascript
   tags:
   - dynamic-section
   enabled: true
   scripttarget: 0
   runonce: false
   runas: DBotWeakRole

3. Add the script to the layout and then add the layout to the incident type.
4. Go to the incident to view the note information.

   You can see note information, containing the last user and date.

   

   incident-note.png