Using InSyncs

This topic covers a feature that is not available for all customers yet. See Early Access Program Features and Topics Under Development.

InSyncs synchronizes ServiceNow and Stellar Cyber to streamline case management and enhance communication between the two systems.

Using InSyncs, you can:

• Open and close a Stellar Cyber case in ServiceNow.

• Update a case in Stellar Cyber, which updates a ticket in ServiceNow.

• Request information from ServiceNow and update the Activity Log in Stellar Cyber.

• Retrieve data from ServiceNow data tables to update cases in Stellar Cyber.

• Post data from Stellar Cyber cases to update ServiceNow data tables.

• Delete a Stellar Cyber case, which deletes a case in ServiceNow.

To ensure the data is synchronized, Stellar Cyber listens for updates from ServiceNow and updates the Stellar Cyber cases or alerts every five minutes when changes occur. Updates from Stellar Cyber to ServiceNow are performed live and are applied immediately.

For more information, see the following:

• Using the InSyncs Table

• Configuring InSyncs

• Viewing InSyncs in Alerts

• Viewing InSyncs in Cases

Using the InSyncs Table

To configure and view integration syncs, select System | InSyncs (under Integrations).

The InSyncs Overview table is displayed in the InSyncs tab.

The InSyncs Overview table has the following columns:

• Name—name of the integration sync (or InSync)

• Tenant Name—All Tenants means that the integration sync can be used across tenants

• Status—status of the integration sync:

  • Success (green)

  • Error (red)

  • Inactive (gray)

• Messages—messages about the Status

• Type—type of integration sync, such as ServiceNow

• Pause/Sync—toggle of the integration sync

• Actions—actions available for an integration sync, such as Edit this row, Delete this row, or Test.

Using Search

Use the Search box to search for information about an InSync.

Using Filters

Click Filters to use defined filters.

To use defined filters:

• For Name, select the name of an integration sync using the check boxes or Select All. The number of integration syncs of each name is displayed on the right.

  

• For Status, select the status using the check boxes or Select All. The number of integration syncs of each status is displayed on the right.

  

• For Messages, select the message using the check boxes or Select All. The number of integration syncs of each message is displayed on the right.

  

• For Type, select the type using the check boxes or Select All. The number of integration syncs of each type is displayed on the right.

  

• For Pause/Sync, select either Pause or Sync using the check boxes or Select All. The number of integration syncs of each toggle is displayed on the right.

  

• For Tenant Name, select All Tenants or Select All.

  

• You can click the Select filter search box under Add new filter to deselect a filter in the dropdown menu.

  

• You can also type in the Select filter search box under Add new filter to search for a filter.

  

To exit, click Filters again. The configured filters are displayed at the top of the table.

To clear an individual filter, click the icon to the right of the filter ().

To clear all filters, click Clear All.

Using Columns

Pausing InSyncs

To pause an integration sync, click the toggle in the Pause/Sync column from Sync to Pause.

Starting InSyncs

To start an integration sync, click the toggle in the Pause/Sync column from Pause to Sync.

Editing InSyncs

To edit an existing integration sync, click the Edit icon () on a row in the table. The Edit ServiceNow InSync dialog displays.

To create an integration sync, see Configuring InSyncs.

Deleting InSyncs

To delete an integration sync, click the Trash icon () in the Actions column for a row in the table.

Testing InSyncs

To test the integration sync, click Test. A message displays.

Test only validates credentials, whereas Status reflects the import and export of data between ServiceNow and Stellar Cyber. Even when the integration sync is in Error status, the credential test can be successful.

Configuring InSyncs

You can create up to three InSyncs. During the configuration, you will authenticate the user with ServiceNow, select the type of integration sync (alerts, cases, or both), and provide the name of a ServiceNow alert database table, case database table, or both.

You need a User role that has access to the system dictionary to read field attributes for InSyncs configuration. If you know the name of the ServiceNow table, you need a User role that has access to the table (for reading, creating, and deleting the records in that table). To create a non-admin user and assign roles to it, refer to Creating an App, Tables, and a Default User Role and Creating a Non-Admin User and Assigning a Role.

Make sure that the rules created in ServiceNow will not interfere with the creation of records in the table. If a ServiceNow rule requires certain fields to be populated, and if those fields are not available on Stellar Cyber, the record may not be created.

To create an integration sync:

1. Click Create.

   

   The asterisk (*) indicates a required field.

2. Enter a unique name for the integration sync in the InSync Name field.

3. (Optional) You can toggle Sync after creation to disabled. It is enabled by default.

4. Click Next.

   

   The asterisk (*) indicates a required field.

5. The authentication type is Basic, which is already selected.

6. Enter the URL to which to synchronize, for example, https://myaccount.service-now.com.

7. Enter the Username.

8. Enter the Password.

9. (Optional) You can toggle Sync after creation to disabled. It is enabled by default.

10. Click Next.

11. Select the type of configuration using the buttons for Cases, Alerts, or Both. Depending on your selection, the configuration options are:

    For Cases:

    

    1. (Optional) Select Filters. You can select filters by Assignee, Severity (Critical, High, Medium, or Low), or Status (Canceled, Escalated, In Progress, New, or Resolved). The default is all the case filters.

    2. (Optional) Select Tenant. You can filter by a specific tenant or All Tenants. The default is All Tenants.

       

       The asterisk (*) indicates a required field.

    3. Select a Score range from 0 to 100 using the slider.

    4. Enter the name of a Case database table in ServiceNow from which to collect data, then click Confirm to verify the database table. A message displays if the database table cannot be found or if fields in the database table cannot be found. To obtain table names, see Obtaining ServiceNow Table Names.

       If the ServiceNow database table is created from an extensible table, only the fields created from the current table, not the parent table, can be used for field mapping.

    5. For Field Mapping, match the fields on Stellar Cyber and ServiceNow to synchronize them. If the fields do not match, they will not be synchronized.

       Stellar Cyber sends their status to ServiceNow. If the ServiceNow status is changed or updated to a status that matches in Stellar Cyber (case-sensitive), it updates.

       

       The Stellar Cyber fields are on the left side of the Field Mapping table, the arrows in the center of the table indicate the direction of the field mapping, and the ServiceNow fields are on the right side of the table.

       In this example, the Stellar Cyber Case Name field is mapped to Name in ServiceNow with bidirectional synchronization (Case Name to Name and Name to Case Name) and the Tenant Name is mapped to Description with unidirectional synchronization.

       Unmapped means that the selected field maps to Null.

       In the Field Mapping table, you can select the ServiceNow fields from the drop-down menus, which have different options depending on the ServiceNow database table.

       With field mapping, a field type of string can only map to a string field. Likewise, a URL field can only map to a URL. For details, see Supported Field Types.

    For Alerts:

    

    1. (Optional) Select Filters. You can select filters by Source (Built-in or Custom) or Status (Closed, Ignored, In Progress, or New). The default is all the alert filters.

    2. (Optional) Select Tenant. You can filter by a specific tenant or All Tenants. The default is All Tenants.

       

       The asterisk (*) indicates a required field.

    3. Select a Score range from 0 to 100 using the slider.

    4. Enter the name of an Alert database table in ServiceNow from which to collect data, then click Confirm to verify the database table. A message displays if the database table cannot be found or if fields in the database table cannot be found. To obtain table names, see Obtaining ServiceNow Table Names.

       If the ServiceNow database table is created from an extensible table, only the fields created from the current table, not the parent table, can be used for field mapping.

    5. For Field Mapping, match the fields on Stellar Cyber and ServiceNow to synchronize them. If the fields do not match, they will not be synchronized.

       Stellar Cyber sends their status to ServiceNow. If the ServiceNow status is changed or updated to a status that matches in Stellar Cyber (case-sensitive), it updates.

       

       The Stellar Cyber fields are on the left side of the Field Mapping table, the arrows in the center of the table indicate the direction of the field mapping, and the ServiceNow fields are on the right side of the table.

       In this example, the Stellar Cyber Alert Name field is mapped to alert name in ServiceNow with unidirectional synchronization and the Assignee is mapped to Updated by with bidirectional synchronization (Assignee to Updated by and Updated by to Assignee).

       Unmapped means that the selected field maps to Null.

       In the Field Mapping table, you can select the ServiceNow fields from the drop-down menus, which have different options depending on the ServiceNow database table.

       With field mapping, a field type of string can only map to a string field. Likewise, a URL field can only map to a URL. For details, see Supported Field Types.

    For Both:

    

    1. Click the Cases tab to configure the same fields as for Cases above.

    2. Click the Alerts tab to configure the same fields as for Alerts above.

12. (Optional) You can toggle Sync after creation to disabled. It is enabled by default.

13. Click Submit. Once an InSync is created, you can view it in Alerts.

Creating an App, Tables, and a Default User Role

You can create a default user role, which you will need to assign to a non-admin user, when you create an app.

To create an app, the alert and cases database tables, and a default user role:

1. In the App Engine Studio, click Create app.

   

2. Enter a name for the app and click Continue.

   

3. An admin role name and a user role name are automatically created. You can change the name of the user role name and click Continue.

   

4. Wait for the app to be created, then click Go to app dashboard.

   

5. Create two database tables, one for alerts and one for cases. To get started, click Add in the Data section.

   

6. Click Create a blank table and click Continue.

   

7. Click Create new table and click Continue.

   

8. Give the table a name, such as Cases, and click Continue.

   

9. Add permissions to your table. Select All for both the admin role and the user role, then click Continue.

   

10. Wait for the table to be added, then click Edit table.

    

11. Add the columns to the table that are listed in Supported Field Types. (There are different supported field types for cases and for alerts.) To get started, click Add field.

    

12. Enter the Column label and Column name, select a Type, and click Add.

    

13. The column is added. Click Add field to continue adding columns to the table.

    

14. You can go to the App Home to see the created table.

    

15. To create another table, such as Alerts, click Add.

16. Repeat the previous steps to create the other table and add the columns to it. When finished, there are two tables, one for Cases and one for Alerts.

    

17. Click the Security tab. (To access this tab, you must be an admin user.) The Default user role needs to be assigned to a user. Go to the procedure for Creating a Non-Admin User and Assigning a Role.

Creating a Non-Admin User and Assigning a Role

You need a User role that has access to the system dictionary to read field attributes for InSyncs configuration. If you know the name of the ServiceNow table, you need a User role that has access to the table (for reading, creating, and deleting the records in that table).

To create a non-admin user and assign roles to it:

1. In ServiceNow, click the All tab, and search for Users under User Administration.

   

2. Click New.

   

3. Enter the information for the new user and click Submit.

   

4. Locate the user you created.

   

5. Select the user to edit it, then select the Roles tab and click Edit.

   

6. Search in the Collection for the personalize_dictionary. Also search for a previously created role, which will start with x_ and have the previously created role as part of the role name (a sys_id). Click the right arrow (>) to move a role from the Collection to the Roles List.

   

7. Click Save. The roles are added.

   

8. You can also add additional roles, but these two roles are required.

   To set a password for the user at this time, you can click Set password.

Obtaining ServiceNow Table Names

If you know the name of the ServiceNow table, you need a User role that has access to the table (for reading, creating, and deleting the records in that table). If you do not know the name of the ServiceNow table, you need an Admin role to obtain it.

In the following procedure, the menu item for System Definition | Tables is only displayed for a User Role of Admin in ServiceNow.

For example, to change your role to Admin if your role was App Engine Studio Creator, navigate to Change User Role. click Admin, and then click Change User Role.

To obtain table names in ServiceNow:

1. In the main ServiceNow browser window, navigate to the All menu, click System Definition, and then click Tables.

   

2. In the Tables list, click the table Label.

   

3. Note the table Name.

   

Supported Field Types

The following table describes the supported field types for cases.

It is recommended you configure URL fields with URL type and other string fields with String (Full UTF-8) type.

Field Name	Stellar Cyber Field	Stellar Cyber Field Type	Direction	ServiceNow Field Types Supported
Case Name	name	string	Both	String, String (Full UTF-8)
Who	details.who	list	Out	String, String (Full UTF-8)
What	details.what	list	Out	String, String (Full UTF-8)
When	details.when	int	Out	String, String (Full UTF-8), Date/Time
Where	details.where	list	Out	String, String (Full UTF-8)
Severity	severity	string	Out	String, String (Full UTF-8)
Status	status	string	Both	String, String (Full UTF-8)
Assigned to	assignee_name	string	Both	String, String (Full UTF-8)
Score	score	float	Out	String, String (Full UTF-8), Decimal, Floating Point Number, Integer, Long
Stellar Case URL	case_url	string	Out	URL, String, String (Full UTF-8)
Case ID	ticket_id	string	Out	String, String (Full UTF-8)
Tenant ID	cust_id	string	Out	String, String (Full UTF-8)
Tenant Name	tenant_name	string	Out	String, String (Full UTF-8)

The following table describes the supported field types for alerts.

It is recommended you configure URL fields with URL type and other string fields with String (Full UTF-8) type.

Field Name	Stellar Cyber Field	Stellar Cyber Field Type	Direction	ServiceNow Field Types Supported
Alert Name	xdr_event.display_name	string	Out	String, String (Full UTF-8)
Alert Description	xdr_event.description	string	Out	String, String (Full UTF-8)
Stage	xdr_event.xdr_killchain_stage	string	Out	String, String (Full UTF-8)
Tactic	xdr_event.tactic.name	string	Out	String, String (Full UTF-8)
Technique	xdr_event.technique.name	string	Out	String, String (Full UTF-8)
Score	event_score	float	Out	String, String (Full UTF-8), Decimal, Floating Point Number, Integer, Long
Fidelity	fidelity	float	Out	String, String (Full UTF-8), Decimal, Floating Point Number, Integer, Long
Severity	severity	int	Out	Integer, String, String (Full UTF-8)
Threat Intel	threat_score	int	Out	Integer, String, String (Full UTF-8)
Data Period	data_period	int	Out	String, String (Full UTF-8)
Status	event_status	string	Both	String, String (Full UTF-8)
Assignee	assignee	string	Both	String, String (Full UTF-8)
Alert URL	alert_url	string	Out	URL, String, String (Full UTF-8)
Tenant ID	tenantid	string	Out	String, String (Full UTF-8)
Tenant Name	tenant_name	string	Out	String, String (Full UTF-8)

Viewing InSyncs in Alerts

Click Alerts to go to the Alerts page. At the top of the page, there is a status indicator for the integration syncs as well as a button you can click to go back to the InSyncs page.

Viewing the Alert Type Table

At the bottom of the Alerts page, click View on a specific alert type in the table to go deeper into the alert. In this example, click View on the row for the alert type Abnormal Parent / Child Process.

Viewing Alert Details

If you want to copy the ticket ID, click the JSON tab and search for insyncs and locate the source_id field.

The JSON also contains the ServiceNow link (source_link).

Adding a New Case from Alerts

From the Alerts page, you can add a new case. The new case will be created and synchronized automatically with ServiceNow.

Select a row in the Alert details table, click Add to Case, and select New Case.

Viewing InSyncs in Cases

Click Cases to go to the Cases page. At the top of the page, there is a status indicator for the integration syncs as well as a button you can click to go back to the InSyncs page.

Viewing the Cases Table

Scroll down to the Cases table. The table has an InSyncs column showing the cases that have been linked. When you hover over a NOW icon in the InSyncs column, the status, Ticket ID, and Last Synced date and time are displayed.

Click a Case Name in the table on the Cases page to go to the Case Details page.

Viewing the ServiceNow Record

Click the Ticket ID link in the status indicator on the Case Details page to open the ServiceNow record.

If you added a new case, it is added to the ServiceNow table. You may have to refresh the window.

Updating the Case Name Example

As an example, you can change the name of a case in Stellar Cyber and see it changed in ServiceNow:

1. Click on the name of a case in the Case Details page, then type a new case name in Stellar Cyber.

   

2. The case name in ServiceNow is updated. You may have to refresh the window.