Common Use cases

The typical use case is when UpGuard has found an issue or risk and you want to manage this in ServiceNow. Any Notification within UpGuard can be sent as an 'Integration' to ServiceNow.

Commonly used Notifications for sending to ServiceNow are:

  • "When a new identity breach is detected" or "When a new identity breach for a VIP email is detected"

  • "When a new data leak is published" and/or "When a new data leak is disclosed for one of your vendors"

  • "When a typosquatting domain becomes registered"

  • "When new vulnerabilities are detected on a domain or IP"

Additionally consider a Notification for when Risks are added of a chosen severity. To add this, you first need to create a Custom Notification:

  1. In Settings > Notifications > Create Notification Choose 'When risks are added to my domains and IPs' and choose a minimum severity level. To capture all risks choose 'Info'.

  2. Then when creating the Integration, look for "When risks are added to my domain and IPs that are info severity or greater"

Ways to integrate with ServiceNow

The options to integrate with ServiceNow's ITSM package (to create Incidents, Problem, Change records) from UpGuard are:

  • UpGuard Webhook to ServiceNow Scripted Rest API

  • UpGuard Webhook to Zapier to ServiceNow

  • UpGuard Email notification to ServiceNow incoming Email flow

  • UpGuard Webhook to ServiceNow Rest API

This document is going to explain how to achieve the last type, as using the ServiceNow Rest API is the simplest and fastest way to achieve the desired integration.

The following sections will explain how to achieve the integration optionally with more flexibility:

  1. Quickly get UpGuard events into Incident records in ServiceNow.

  2. Expanding on the initial setup to use alternative fields in ServiceNow.

  3. Sending events to Security Incident records (which is an extension of normal Incident records).

Integrating UpGuard events into Incident records

Setup in ServiceNow:

In ServiceNow start by creating a new Service Account (User):

Go into ServiceNow, select 'All' in the Navigator Options. Search for 'Users and Groups' and select the 'Users'.

Create a new user, we suggest something like 'svc_api_upguard' with a password that will be used later.

Also check the 'Web service access only' which will limit the user to API actions and no UI login allowed.

user 
user ID 
First name 
Last name 
Department 
Password 
Password needs reset 
Locked out 
Active 
Web service access only 
Internal Integration user 
Date format 
Submit 
Related Links 
View linked accounts 
View Subscriptions 
svc_api_upguard 
upguard 
service-account 
System (

For the Common Use cases:

In UpGuard, go to Settings > Integrations > 'New Integration' > Webhook.

We suggest choosing the ID Breaches, Data Leaks, and TypoSquatting notifications as the initial set of alerts. See the Common Use Cases for the complete names of these.

Integration Settings > Create Integration 
Create Integration 
Triggers 
Select triggers 
Organization triggers 
The following are organization triggers. 
Vendor triggers 
The following are vendor triggers. 
@ Name and destination 
Trigger 
When a new data leak is published 
When a new message is posted on a data leak 
Trigger 
@ Review payload 
When a new data leak is disclosed for one of your vendors 
When a new data leak is closed for one of your vendors 
Cancel 
Enable/disable 
x 
Enabled 
Enabled 
Confirm and next
Integration Settings > Create Integration 
Create Integration 
Triggers 
Select triggers 
Q vuln 
Organization triggers 
The following are organization triggers. 
@ Name and destination 
Trigger 
@ Review payload 
When new vulnerabilities are detected on a domain or IP 
Cancel 
Enable/disable 
x 
Enabled 
Confirm and next
Integration Settings > Create Integration 
Create Integration 
Triggers 
Select triggers 
Q typo 
Organization triggers 
The following are organization triggers. 
@ Name and destination 
Trigger 
When a typosquatting domain becomes registered 
@ Review payload 
When the registration details for a typosquatting domain change 
Cancel 
Enable/disable 
x 
Enabled 
Confirm and next
Integration Settings > Create Integration 
Create Integration 
Triggers 
Select triggers 
Q breach 
Organization triggers 
The following are organization triggers. 
@ Name and destination 
Trigger 
When a new identity breach is detected 
When a new identity breach for a VIP email is detected 
@ Review payload 
Cancel 
Enable/disable 
x 
Enabled 
Confirm and next

Once you have chosen the Notifications (AKA Triggers) that you want to use, click 'Confirm and Next'

Fill in the details. Some example values are:

Name: UpGuard alerts to ServiceNow Incident

Webhook URL: https://<youinstance>.service-now.com/api/now/table/incident

HTTP Headers:

  1. Accept | application/json

  2. Content-Type | application/json

Basic authentication: svc_api_upguard | <password_set_above>

@ Triggers 
Name & destination 
Name of the integration* 
Please provide a name for this integration. 
Webhook URL* 
Please enter the URL of the webhook. 
HTTP headers 
Configure any HTTP Header values required to connect 
to your URL. 
HTTP URL parameters 
Configure any URL parameter values required to connect 
to your URL. 
Basic authentication 
If your URL implements HTTP Basic Authentication, 
configure a username/password here. 
Go back 
@ Name and destination 
UpGuard alerts to Service Now incident 
(S) Review payload 
https://XXXXXX)4.service-now.com/api/now/table/incident 
Accept 
Content-Type 
Name 
Name 
svc_api_upguard 
application/json 
application/json 
Cancel 
@ Enable/disable 
Confirm and next

Once configured move on with Confirm and Next.

Next, in the triggers list to the left, for the triggers "When a new identity breach is detected" and "When a new identity breach for a VIP email is detected" you should replace the payload template with something like this:

{
"correlation_id":"{{ notification.context.BreachUrl }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has detected an Identity Breach - {{ notification.context.BreachID }} - {{ notification.context.BreachName }}.\r\nThis is for email domain - {{ notification.context.Domain }}.\r\nFollow this link to see more details in UpGuard {{ notification.context.BreachUrl }}",
"impact":"2"
}

Send a Test message. If you see a 201, then look in ServiceNow in 'All Incidents' for the new Incident.

Continue to change each Payload Template. Example payloads for each of the Common Use cases are shown below (change the impact as required):

When a new data leak is published:

{
"correlation_id":"{{ notification.context.FindingUrl }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has detected a new Data Leak - {{ notification.context.FindingId }} - {{ notification.context.FindingName }}.\r\nSee more details at {{ notification.context.FindingUrl }}",
"impact":"1"
}

When a new data leak is disclosed for one of your vendors:

{
"correlation_id":"{{ notification.type }}{{ notification.context.VendorName }}{{ notification.context.DisclosedAt }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has detected a new Data Leak for Vendor - {{ notification.context.VendorName }} at {{ notification.context.DisclosedAt }}.\r\nSee more details at https://cyber-risk.upguard.com/vendordataleaks ",
"impact":"2"
}

When a typosquatting domain becomes registered:

{
"correlation_id":"{{ notification.context.SquatDomain }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has detected a new TypoSquatting domain of {{ notification.context.SquatDomain }} which is similar to {{ notification.context.Domain }}.\r\nSee https://cyber-risk.upguard.com/typosquatting for more info",
"impact":"2"
}

When new vulnerabilities are detected on a domain or IP:

{
"correlation_id":"{{ notification.type }}{{ notification.context.Domain }}{{ notification.occurredAt }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has added the following Vulnerabilities to {{ notification.context.Domain }} at {{ notification.occurredAt }}.\r\n{% for value_3 in notification.context.CVENames %}{{ value_3 }}\r\n{% endfor %}",
"impact":"2"
}

When risks are added to my domain and IPs that are info severity or greater:

{
"correlation_id":"{{ notification.type }}{{ notification.context.Domain }}{{ notification.context.ScannedOn }}",
"short_description":"{{ notification.description }}",
"description":"UpGuard has discovered new risks on your domain {{ notification.context.Domain }} at {{ notification.occurredAt }}.\r\nPlease review these risks for possible remediation or waivers. List of Risks with Severity:\r\n{% for value_3 in notification.context.RisksSummary %} Title: {{ value_3.Title }} Severity: {{ value_3.Severity }}\r\n{% endfor %}",
"impact":"2"
}

For other notification types:

Copy the existing payload template into a text editor

Paste a simple payload template like this, into UpGuard:

{
"correlation_id":"",
"short_description":"{{ notification.description }}",
"description":"\r\n",
"impact":"2"
}

Copy the appropriate variables from the saved payload template into the correlation_id and/or the description values (see previous common use cases as examples).

Please note: For the ServiceNow API, the data between the “” for the values cannot have new line characters so the quotes need to be on a single line. Use ‘\r\n’ to insert a new line in any field that allows this.

Send a Test message. If you see a 201, then look in ServiceNow in 'All Incidents' for the new Incident, to check the example values that were passed.

Expanding on the initial setup to use alternative fields in ServiceNow

Finding and using additional ServiceNow attributes:

First, we want to find out which fields/attributes could be populated for a particular table in ServiceNow. We will use the ServiceNow ‘Rest API Explorer’ after creating an example record.

First, in ServiceNow, create an example record. Use the ‘Default view’ (or some other expanded view) rather than the ‘Self-Service’ view, so you can see all the fields. Create a record:

Take note of the ‘number’. Here it is ‘INC0029586’.

Now, select 'All' in the Navigator Options.

Search for 'Rest API Explorer' and set 'namespace' to 'now' and 'API' to 'Table API'.

Choose 'Retrieve records from a table (GET)' and choose 'incident'.
Scroll down until you see ‘Request format' and 'Response format’. They should both be set to 'application/json'.

Enter ‘number=INCnnnnnnn’ into ‘sysparm_query’ and click ‘Send’:

The response will be similar to:

{
"result": [
{
"parent": "",
"made_sla": "true",
"caused_by": "",
"watch_list": "",
"upon_reject": "cancel",
"sys_updated_on": "2022-06-20 22:05:29",
"child_incidents": "0",
"task_effective_number": "INC0029586",
"approval_history": "",
"skills": "",
"number": "INC0029586",
"resolved_by": "",
"sys_updated_by": "admin",
"opened_by": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/sys_user/6816f79cc0a8016401c5a33be04be441",
"value": "6816f79cc0a8016401c5a33be04be441"
},
"user_input": "",
"sys_created_on": "2022-06-20 22:05:29",
"sys_domain": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/sys_user_group/global",
"value": "global"
},
"state": "2",
"route_reason": "",
"sys_created_by": "admin",
"knowledge": "false",
"order": "",
"calendar_stc": "",
"closed_at": "",
"cmdb_ci": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/cmdb_ci/46b87032a9fe198101b2df13015be972",
"value": "46b87032a9fe198101b2df13015be972"
},
"delivery_plan": "",
"impact": "2",
"active": "true",
"work_notes_list": "",
"business_service": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/cmdb_ci_service/d4e69e230a0a3c152e3a0cd4c1ef2107",
"value": "d4e69e230a0a3c152e3a0cd4c1ef2107"
},
"vulnerability": "",
"priority": "2",
"sys_domain_path": "/",
"rfc": "",
"time_worked": "",
"expected_start": "",
"opened_at": "2022-06-20 21:59:00",
"business_duration": "",
"group_list": "",
"work_end": "",
"caller_id": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/sys_user/d6826bf03710200044e0bfc8bcbe5da7",
"value": "d6826bf03710200044e0bfc8bcbe5da7"
},
"reopened_time": "",
"resolved_at": "",
"approval_set": "",
"subcategory": "ip address",
"work_notes": "",
"universal_request": "",
"short_description": "A Short Description",
"close_code": "",
"correlation_display": "",
"delivery_task": "",
"work_start": "",
"assignment_group": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/sys_user_group/28e5fabfb78b001004aae3fdde11a919",
"value": "28e5fabfb78b001004aae3fdde11a919"
},
"additional_assignee_list": "",
"business_stc": "",
"description": "The long description\r\nwith newline\r\ninside\r\n",
"calendar_duration": "",
"close_notes": "",
"notify": "1",
"service_offering": "",
"sys_class_name": "incident",
"closed_by": "",
"follow_up": "",
"parent_incident": "",
"sys_id": "d2201c581b189d10ffadeb95604bcb42",
"contact_type": "self-service",
"reopened_by": "",
"incident_state": "2",
"urgency": "1",
"problem_id": "",
"company": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/core_company/31bea3d53790200044e0bfc8bcbe5dec",
"value": "31bea3d53790200044e0bfc8bcbe5dec"
},
"reassignment_count": "0",
"activity_due": "",
"assigned_to": {
"link": "https://XXXXXXXX.service-now.com/api/now/table/sys_user/8d56406a0a0a0a6b004070b354aada28",
"value": "8d56406a0a0a0a6b004070b354aada28"
},
"severity": "3",
"comments": "",
"approval": "not requested",
"sla_due": "",
"comments_and_work_notes": "",
"due_date": "",
"sys_mod_count": "0",
"reopen_count": "0",
"sys_tags": "",
"escalation": "0",
"upon_approval": "proceed",
"correlation_id": "",
"location": "",
"category": "network"
}
]
}

From this we can deduce these field names and values are equivalent:

Form field

Form value

API field

API value

Number

INC0029586

number

INC0029586

Caller

Steve Schor

caller_id

d6826bf03710200044e0bfc8bcbe5da7

Category

Network

category

network

Subcategory

IP Address

subcategory

ip address

Business Service

This Service-now instance

business_service

d4e69e230a0a3c152e3a0cd4c1ef2107

Configuration item

4300S-020220

cmdb_ci

46b87032a9fe198101b2df13015be972

Short description

A Short Description

short_description

A Short Description

Description

The long description

with newline

inside

description

The long description\r\nwith newline\r\ninside\r\n

Contact type

Self-service

contact_type

self-service

State

Active

state

2

Impact

2 - Medium

impact

2

Urgency

1 - High

urgency

1

Priority

2 - High

priority

2

Assignment group

Vulnerability Analyst

assignment_group

28e5fabfb78b001004aae3fdde11a919

Assigned to

Eric Schroeder

assigned_to

8d56406a0a0a0a6b004070b354aada28

The next step is to test adding a record using the API. In the Rest API Explorer, click on ‘Create a record (POST)’, choose the table again ‘incident’. In ‘Request Body’ click ‘Add field’, choose the fields you want to add, and the values. Click Send, and when prompted with “Modifying data, confirm to continue”, click OK. You should now be able to view the record that was created, and check if the values were created as expected.

Copy the ‘Request Body’ and use this in UpGuard’s payload template.

Extracting from the example above, this could be pasted into UpGuard:

{
"caller_id":"d6826bf03710200044e0bfc8bcbe5da7",
"category":"network",
"subcategory":"ip address",
"business_service":"d4e69e230a0a3c152e3a0cd4c1ef2107",
"cmdb_ci":"46b87032a9fe198101b2df13015be972",
"short_description":"{{ notification.description }}",
"description":"The long description\\r\\nwith newline\\r\\ninside\\r\\n",
"contact_type":"self-service",
"state":"2",
"impact":"2",
"urgency":"1",
"priority":"2",
"assignment_group":"28e5fabfb78b001004aae3fdde11a919",
"assigned_to":"8d56406a0a0a0a6b004070b354aada28"
}

Note: In the above, we added each attribute on a new line, and we replaced the Short Description value with a variable.

Sending events to Security Incident records:

Within ServiceNow, there is a different kind of table, called ‘Security Incident’ (sn_si_incident). This is often used by CyberSecurity teams instead of the basic ‘incident’ type. The process for using this is similar to that shown above but instead substitute ‘sn_si_incident’ for ‘incident’.

Also, you will need to grant additional permissions to the API user. Open the user to be used for API access, in the ‘Roles’ tab, click ‘Edit’. Search for ‘sn_si_’ and add the roles sn_si_basic and sn_si_integration_user. Leave any existing roles do not remove roles, only add some if needed, as the existing ones may have been derived from ServiceNow upgrades and other permissions.

Edit Members 
— choose field — 
Collection 
sn_si. 
si admin 
sn 
sn_si analyst 
si .ciso 
sn 
si external 
sn 
sn_si .knowledge_admin 
sn_si .manager 
si.read 
sn 
sn_si special_access 
Name sn si.basic 
Cancel 
— oper — 
Cancel 
— value — 
Roles List 
upguard service-account 
si.basic 
Save

Related Articles

Did this answer your question?