How to integrate with ServiceNow

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.

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.

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>

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:

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.

Related Articles

• How to integrate UpGuard with other services

• Using Liquid syntax to customize your integration

• How to set up a Slack integration in UpGuard

• How to create an email integration in UpGuard

• How to send notifications to Splunk from UpGuard