Skip to main content

ServiceNow

Visualize ServiceNow resources and monitor them through queries and alerts.

Installation​

ServiceNow Setup Requirements

Before configuring this integration in JupiterOne, create a dedicated service account with read access in ServiceNow:

Required in ServiceNow:

  • A dedicated service account user (for example, JupiterOne)
  • A custom read-only role (for example, jupiterone_reader)
  • Access Control Lists (ACLs) that grant that role read access to the required tables
  • Your ServiceNow instance hostname (for example, yourcompany.service-now.com)

Authentication: This integration uses HTTP Basic authentication with a username and password.

Required table access: The service account must have read access to these base tables:

  • sys_user - user data
  • sys_user_group - group data
  • sys_user_grmember - group membership data
  • incident - incident data
  • sys_db_object - table metadata used to resolve CMDB classes
  • core_company - company data

Additional roles for optional data:

  • CMDB: to ingest CMDB items, views and relationships, add the cmdb_read role, which grants read access to the cmdb_ci tables as well as cmdb_rel_type and cmdb_rel_ci.
  • Incidents: incidents are read from the incident table. The itil role grants this access; alternatively, grant read on incident through the custom role's ACLs.
  • Vulnerable Items: requires the licensed Vulnerability Response application and the sn_vul.read_all role.
  • Configuration Compliance: requires the licensed Configuration Compliance application and the sn_vulc.read role.

Optional write access: If you want JupiterOne to create ServiceNow incidents from alert rules, create an additional role (for example, jupiterone_incident_creator) with Create access to the incident table.

Detailed setup instructions are provided in the Configuration in ServiceNow section below.

To allow JupiterOne to fetch data from your ServiceNow account, create a ServiceNow role with read-only access, grant it the tables above through ACLs, and assign it to a dedicated ServiceNow user.

note

ServiceNow enforces MFA on interactive (human) user accounts, which blocks Basic-auth API sign-in. Make the service account API-only by enabling Web service access only on the user record, and set a local password so Basic authentication can use it.

Configuration in ServiceNow​

  1. Create a read-only role. Go to All > User Administration > Roles > New and create a role named jupiterone_reader.

  2. Create an access control rule (ACL) for each required table. Go to All > System Security > Access Control (ACL) > New and create a rule with Type record, Operation read, Requires role set to jupiterone_reader, and Name set to each table and its fields (<table> and <table>.*). Creating ACLs requires elevating to the security_admin role. Create rules for the following tables:

    • sys_user
    • sys_user_group
    • sys_user_grmember
    • incident
    • sys_db_object
    • core_company
  3. Create the service account user. Go to All > User Administration > Users > New and create a user named JupiterOne. Set a local password, enable Web service access only, and record the username and password; you need them when configuring the integration in JupiterOne.

  4. Assign the role. Open the JupiterOne user, go to Roles > Edit, and add jupiterone_reader. Add any of the following roles for the data you plan to ingest:

    • cmdb_read for CMDB items, database views and relationships. This base system role grants read access to the CMDB tables and is contained in the asset role. See the base system roles reference for details.
    • itil to read the incident table, unless your jupiterone_reader ACLs already grant read on incident.
    • sn_vul.read_all for Vulnerable Items. This requires the licensed Vulnerability Response application.
    • sn_vulc.read for Configuration Compliance test results. This requires the licensed Configuration Compliance application.
  5. (Optional) To let JupiterOne create ServiceNow incidents from JupiterOne alert rules, create an additional role (for example, jupiterone_incident_creator), add an ACL with Type record, Operation create, Name incident and incident.*, and Requires role set to that role, then assign it to the JupiterOne user.

Configuration in JupiterOne​

To install the ServiceNow integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select ServiceNow. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the ServiceNow account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • Your ServiceNow Hostname (for example, j1.service-now.com), Username, and Password.

  • Your ServiceNow CMDB Classes to ingest, as a comma-separated list of classes (up to 20).

Click Create once all values are provided to finalize the integration.

Advanced Options​

Additional configuration can be set to customize the ingested data.

User Configuration

  • Custom fields to include in User entities adds the named custom fields (by field key) to each user entity. Separate fields with commas.
  • Excluded User Classes excludes users whose system class name (sysClassName) matches one you list, so they are not created as User entities.

Host Configuration

  • Host Classes lists the system class names that are treated as hosts and mapped to the JupiterOne Device data model.
  • Custom fields to include in Host entities adds the named custom fields to each host entity.
  • Custom fields to include in CMDB entities adds extra fields to generic CMDB entities, which are otherwise dropped on scoped or custom tables. Use a dot-path for reference fields (for example, primary_owner.value).
  • Fallback name fields for CMDB entities is an ordered list of fields used to name a CMDB entity when its name column is empty. The first field with a value is used, and entities that already have a name are unaffected. Prefix an entry with <sys_class_name>: to apply it to one class only.
  • CMDB owner reference fields lists reference fields whose referenced user owns the CMDB item. Each one produces a user OWNS CMDB relationship in addition to the standard owned_by column.
  • CMDB group reference fields lists reference fields whose referenced group uses the CMDB item. Each one produces a group USES CMDB relationship. This requires the Groups ingestion source.
  • CMDB host names field relates CMDB items to the hosts named in one of their text fields. See Relating CMDB items to hosts by name.
  • CMDB custom field handlers maps a CMDB field key to the handler used to read its value, for columns whose shape the standard mapping does not understand. The only supported handler is commaSeparatedToArray.

CMDB Database Views

  • Database views to ingest lists the ServiceNow database views to ingest, each mapped to the alias of the view's primary joined table. List views here rather than under CMDB Classes, because a view is a join of several tables and is ingested separately, one record per row. This requires CMDB Classes to be set as well.
  • Database view row key columns maps a database view name to the columns whose values identify each row. Leave this unset in almost all cases; set it only to deliberately group rows more coarsely.

Relating CMDB items to hosts by name​

Some ServiceNow instances record which servers an application owns or uses in a text field on the CMDB item, such as a custom Owns or Uses Servers column on cmdb_ci_business_app, rather than (or as well as) in CI relationships. Set CMDB host names field to that field's key (for example u_owns_or_uses_servers) to turn those names into relationships.

  • The field must hold host names separated by commas. Spaces around the names are ignored.
  • Each name is matched case-insensitively against the name of the ingested service_now_cmdb_host entities, so the host classes must be listed in Host Classes and included in the CMDB classes.
  • Each match creates a service_now_cmdb_object USES service_now_cmdb_host relationship. These are added alongside the relationships from the CI relationship table (cmdb_rel_ci) and do not replace them.
  • A name that matches more than one host is skipped, because there is no way to tell which host is meant. Names that match no host are also skipped.
  • Leave the field empty to turn this off.

After a run, this query lists the applications and the hosts they were related to:

FIND service_now_cmdb_object THAT USES service_now_cmdb_host RETURN service_now_cmdb_object.name, service_now_cmdb_host.name

note

Excluded User Classes configuration option:

This J1QL Query can be executed to determine which system class names (sysClassName) of users exist within ServiceNow, after a successful job run without any User Class Exclusions:

FIND service_now_user RETURN count(service_now_user), service_now_user.sysClassName

Data Volume Configuration​

Control how much CMDB, vulnerability and configuration compliance data is ingested from ServiceNow to manage storage and processing volume.

Ingestion Windows​

FieldDescriptionDefaultOptions
Vulnerability Timeframe (days)Only ingest vulnerable items found within the last N days, based on each item's last-found date. Leave empty to ingest all.All agesEnter a number of days (for example, 30)

Data Filtering Options​

FieldDescriptionDefaultOptions
Install Status FilterLimit CMDB items to the listed install statuses, as a comma-separated list of install status values (for example, 1,2,6).All statuses1 In Use, 2 Planned, 6 In Stock, and other values configured in your instance
Vulnerability SeveritiesLimit ingestion to vulnerable items with the selected source severities.Critical, High, MediumCritical, High, Medium, Low, None/Info
Vulnerability StatesLimit ingestion to vulnerable items in the selected states.Open, Under InvestigationOpen, Under Investigation, Closed, In Review, Awaiting Implementation, Resolved, Deferred
Configuration Compliance FilterA raw ServiceNow encoded query applied to the test result table. When set, it replaces the default rather than adding to it. Avoid queries that include passing results on large instances, as they are usually the overwhelming majority of the table.sourceLIKEqualys^resultINFailed,Fail,Error (failing Qualys results)Any ServiceNow encoded query

Advanced Configuration​

FieldDescriptionDefault
Custom fields to include in Company entitiesAdds the named custom fields (by field key) to each company entity. Use a dot-path for reference fields (for example, u_duns.value).None
Vulnerability TableThe ServiceNow vulnerability table to ingest.sn_vul_vulnerable_item
Configuration Compliance TableThe ServiceNow Configuration Compliance test result table to ingest.sn_vulc_result
Scanner Result ID ColumnThe column on the test result table that holds the scanner-assigned result id (the Qualys Posture ID for Qualys Policy Compliance). Leave empty to auto-detect it from source_id, id and external_id.Auto-detect

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.