ServiceNow Setup for Organization Notifications

Expel offers a notification synchronization capability for ServiceNow (synchronization refers to Workbench's ability to continuously update a ticket based on state changes in Workbench).

This guide is the first step of a larger process to enable organization notifications.

After completing the steps on this page, you will be instructed to go to Manage Organization Notifications to set up your actual notifications.

Scope and Limitations

When choosing to set up this integration, remember the following:

1. Only the IT Service Management (ITSM) and Security Incident Response (SIR) modules are supported, and the steps listed in this guide apply to both.
2. This plugin cannot be customized.

   • If you are seeking customizable payloads for organization notifications, please instead utilize webhooks or an email ticketing system.
3. ServiceNow will not be used to ingest your security signal for MDR purposes; it will only be used to support notifications.
4. Synchronization is only available for Workbench Investigations or for Investigations flagged as Incidents.

   • See the Reference section for more information about notification synchronization.

Prerequisites

1. You must have a ServiceNow Administrator account with security_admin privileges.
2. You must be using either the ITSM or SIR module, as these are the two supported modules for this integration.
3. The ITSM or SIR module must already be added and enabled on the ServiceNow account.

Step 1: Configure ServiceNow API Access for Expel

1. Log in to the ServiceNow instance using the administrator account.
2. Elevate your role to security_admin.
3. Navigate to User Administration > Users and select New in the upper right corner.
4. For the User ID field, enter "expeluser". The rest of the fields can be left blank.
5. Select Submit.
6. From the Users list, select expeluser.
7. On the User page, select Set Password.
8. Select Generate. Copy the password and save it to a safe place, as you will need it in a later step.
9. Select Save Password.
10. Select Close.
11. Still on the User page, scroll down to the Roles tab and select Edit.
12. Grant the Expel user the appropriate role, depending on your module, so that it has the required permissions to access the incidents table from the REST APIs.

ITSM Module

1. Enter "incident_manager" in the Collection field.
2. Select incident_manager in the list builder and select > to add it to the Roles List.
3. Select Save.

SIR Module

1. Enter "sn_si.manager" in the Collection field.
2. Select sn_si.manager in the list builder and select > to add it to the Roles List.
3. Select Save.

1. Navigate to System OAuth > Application Registry.
2. Select New in the upper right.
3. Select Create an OAuth API endpoint for external clients.
4. Provide a Name for the registry.
5. The default settings can be left as is.
6. Select Submit.
7. On the Application Registries page, select the name of the registry you just created.
8. Copy the Client ID and Client Secret and save them in a safe place, as you will need these values in a later step.

Step 2: Add ServiceNow as a Security Device in Workbench

1. Log in to Workbench.
2. In the side menu, navigate to Organization Settings > Security Devices.
3. Select Add Security Device.
4. In the search box, type “ServiceNow” and then select the ServiceNow integration.
5. Complete the fields as follows:

   • Name - enter a name that might help you more easily identify this integration, such as “CompanyName ServiceNow”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   • Location - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   • Username and Password - enter "expeluser" for the username, and enter the password you generated in Step 1.
   • Server - enter the URL from the ServiceNow instance you configured the Expel user on in Step 1. For example: https://dev1234.service-now.com.
   • Client ID and Client secret - enter the ID and secret you obtained in Step 1.
   • Module - use the dropdown to select the appropriate option depending on whether you are adding an ITSM or SIR device.
   • Assignment group - this is optional and can be left blank.
   • Console Access - granting Workbench access to your ServiceNow console is optional.
6. Select Save.
7. Your device should be created successfully within a few seconds. A few reminders:

   • To check on the status, select the downward arrow for your device in the first column and choose View details. You can then scroll to the Connection section to see if your device is fully connected.
   • You must refresh the page to see updates.
   • Note that a status of "N/A" for Last successful poll is expected.
   • If your device does not report a healthy connection, check that the values you entered into Workbench are correct. If you need further troubleshooting, contact Support.
8. In the Integrations tab on the Organization Settings page, look for a new section titled ServiceNow, and ensure it says Enabled.

   • If it you find this section and it is enabled, proceed to Step 3: Add Your Organization Notifications.
   • If there is no new ServiceNow section, continue to the next step.
9. In the side menu, navigate to Organization Settings > My Organizations and select the name of your organization.
10. Select the Integrations tab.
11. Scroll to the ServiceNow section and select Enable ServiceNow integration.

Step 3: Add Your Organization Notifications

Now you can begin setting up your organization notifications. See Manage Organization Notifications for instructions. If you wish to enable synchronization as part of your organization notifications, see How to Configure in the Reference section for more information.

For a list of default notifications, see Default Organization Notifications. You can edit these notifications at any time using the instructions in the linked guide above.

Reference

Synchronization Capabilities

Synchronization is only available for Incidents and Investigations. Upon creation of a ServiceNow ticket, any subsequent change or update associated with that Investigation or Incident is captured and logged as a comment on that same ticket.

Fields are not currently updated.

For example, if any of the following occurs, a comment is added to the ServiceNow ticket that was created when the Investigation/Incident opened in Workbench:

• An Expel Alert is added to the Investigation/Incident.
• A Verify/Notify Action is created and sent as part of the Investigation/Incident.
• A Remediation Action is assigned, automated, or completed as part of the Investigation/Incident.

When a ticket is created, the following fields are set:

• Title - name of Workbench event (example: [ORG-XXX] Incident created: Authentication from suspicious country)
• Description - includes the URL to the Workbench event (Incident or Investigation) and details about the event.
• Incident State - set to In Progress.
• Caller - set to Expel Integration.

How to Configure

There is a specific action of has any state change within organization notifications for the Investigation and Incident event types, and it is only supported for ServiceNow. When configuring notifications for this set of conditions, set the notify via destination to ServiceNow.

Once saved, whenever an Investigation or Incident is updated in Workbench, comments are appended to the associated ServiceNow ticket. The comments include a URL back to the original Investigation or Incident, and details about the update.

Supported Synchronization Events

For the below events, one ServiceNow ticket is created and continuously updated throughout the lifecycle of the Investigation or Incident.

Workbench Event	State or Action	What Happens in ServiceNow
Incident	Created	Ticket created
Incident	Assigned Closed Downgraded Promoted Reopened Remediation Action assigned/completed/failed	Comment added to ticket
Investigation	Created	Ticket created
Investigation	Alert added Assigned Closed Reopened Investigative Action created/assigned/approved/denied (this includes Verifies)	Comment added to ticket

Unsupported Synchronization Events

For the below events, one unique ServiceNow ticket is created for each event. For example, if configured, a new Expel Alert would yield one ServiceNow ticket. If configured, when that Expel Alert is closed, it would yield another ServiceNow ticket.

Workbench Event	State or Action	What Happens in ServiceNow
Expel Alert	Created	Ticket created
Investigative Action	Analysis assigned Assigned Manual action	Ticket created
Notify Action	Assigned	Ticket created
Verify Action	Assigned Approved Denied	Ticket created
Custom Rule	Created	Ticket created
Assembler Health Status Change	First Time Healthy Unhealthy Healthy	Ticket created
Security Device Health Status Change	First Time Healthy Unhealthy Healthy	Ticket created