Guides
Start typing to search…

ServiceNow (Tables API)

Integrate with and federate search to any ServiceNow Table using the Query Security Data Mesh Connector for ServiceNow

📘

TL;DR

To integrate ServiceNow with Query:

  • Create or identify an existing Integration or normal (human) User.
  • Create a new Role.
  • Create new READ ACLs for the Role - the minimum necessary required ACLs include: sys_db_object, sys_db_object.*, sys_dictionary, and sys_dictionary.*. Plus any other table (and relationship table) you wish to onboard.
  • Associate the Role with the Integration/human user.
  • Create a new OAuth - Resource Owner Password Credentials Grant inbound integration and provide useraccount scope to the Table API.
  • Provide your username, password, Client ID, Client Secret, and table name and use the Configure Schema no-code Wizard to map your SN table data into the Query Data Model/OCSF.
  • Use Query Search to parallelize searches and surface details about CI classes, internal logs, or other table data for incident response (IR), threat hunting, investigations, and other security and observability use cases.

Overview

The ServiceNow Connector for the Query Security Data Mesh enables secure, federated access to your ServiceNow instance without centralizing or duplicating any data. It allows analysts to search, correlate, and analyze ServiceNow records (e.g., incidents, change requests, and assets) alongside telemetry and events from any other connected source, directly through the Query Security Data Mesh.

This Connector exposes ServiceNow’s structured tables (e.g., Incident, Task, Asset, and CMDB) as queryable datasets. Analysts can perform cross-domain investigations, enrich findings with contextual ticket or asset data, and build detections or dashboards that span identity, configuration, and operations data. All of this is possible while preserving ServiceNow’s native access controls and governance.

The Query Security Data Mesh data model is built around the Open Cybersecurity Schema Framework (OCSF) - named the Query Data Model (QDM) - which expresses all search intents with OCSF/QDM concepts such as Entities/Observables used to represent facts and indicators whereas Event Classes represent things that have happened and are normalized against network, application, file system, identity, and 1st party security findings. You will use Configure Schema (or our AI Assistant, Query CoPilot for Configure Schema) to map the source data into these constructs to facilitate federated search, detections, analytics, or otherwise.

Through this integration, Query automatically handles schema discovery, ACL-aware filtering, and parallelized query translation and search against ServiceNow’s Table API. Depending on how you mapped your Tables, this connector ensures that users can issue QDM-style searches, like...

  • "Show me all Incidents that barbarasalazar is assigned to" → QUERY incident_finding.** WITH incident_finding.assignee.name == 'barbarasalazar'
  • "Show me all business applications that were created by jonsmith or an admin" → QUERY cloud_application_inventory_info.resources.** WITH cloud_application_inventory_info.actor.user.name == 'jonsmith' OR cloud_application_inventory_info.actor.user.name ICONTAINS 'admin'
  • "Show me all asset CIs that are running MacOS that aren't use Apple silicon" → QUERY inventory_info.device.** WITH inventory_info.device.os.type_id = MACOS AND inventory_info.device.hw_info.cpu_architecture_id NOT = ARM

...that transparently resolve to the correct ServiceNow tables and fields without manual query building. Once configured, the Query Security Data Mesh treats ServiceNow as a first-class, federated source. This allows teams to investigate indicators of compromise, correlate vulnerabilities to CMDB assets, pivot from incidents to identity or endpoint data, and visualize relationships between ITSM and security datasets without exporting or ingesting records into another platform.

🤓

Some details on searches

Query uses the PySNC library to facilitate authentication & authorization, and as per their recommendation here, we use the OAuth2 - Password Grant Flow.

Since PySNC uses python-requests downstream, only the latin-1 codec is supported. You will likely need to manually reset the password of your integration user and OAuth Client as ServiceNow generates unsupported characters for the passwords/secret value. SAFE CHARACTERS ARE PRINTABLE ASCII, CONTROL CHARACTERS, AND BASIC WESTERN EUROPEAN ACCENTS (0xA0–0xBF and 0xC0–0xFF).

To facilitate listing table schemas and filtering on columns, you must have READ ACLs to sys_db_object, sys_db_object.*, sys_dictionary, and sys_dictionary.* at the very least. These meta tables provide context via linkage for the purpose of schema discovery.

Each Connector is mapped to EXACTLY ONE ServiceNow table and EXACTLY ONE QDM/OCSF Event Class. However, Entities are shared across them allow you to traverse tables irrespective of Event Class mappings by common Entities (e.g., User Name, Resource Name, IP Address) all without memorizing what field name and what table name, all in parallel.

Federated Search Flow

  • Schema Resolution: Fetch configured table’s schema from sys_dictionary including parent tables via recursive traversal of sys_db_object, plus retrieve sample data for field type inference
  • Configure Schema: Map OCSF entity attributes to ServiceNow table columns using the schema information and sample data (performed by the user in go.query UI)
  • Search Translation: Convert OCSF search predicates to ServiceNow encoded query format using discovered schema and field mappings
  • Query Execution: Execute queries against ServiceNow Table API via pysnc client
  • Response Normalization: Transform ServiceNow results back to OCSF format using the same schema mappings

Prerequisites

❗️

Admin Permissions Required

To facilitate the creation of new Users, Roles, ACLs, and Inbound Integrations the following must be true

  1. You have access to an Administrator account.
  2. You can ELEVATE permissions to the security_admin Role.
  3. You have your scope set as GLOBAL.
  4. You have access to the designated integration account for the purpose of resetting the password.

To connect your ServiceNow instance with Query Federated Search for the purpose of conducting searches across your tables you'll need to execute the following steps.

  1. Login to your ServiceNow instance as an Administrator. Select your portrait on the upper-righthand corner of the screen, select Elevate role. From the pop-up, select security_admin, and finally select Update to elevate your role to Security Admin, as shown below (FIG. 1).

    FIG. 1 - Elevating your role to Security Admin in the ServiceNow console

  2. Again on the upper-righthand corner of your screen select the Application scope selector (pictured as a 2D globe of the Earth) and ensure that your Application scope is set to Global as shown below (FIG. 2).

    FIG. 2 - Ensuring Application scope is set to Global in the ServiceNow console

  3. Using the navigation menu, navigate to System Security → Users and Groups → Users. On the top-righthand corner of the screen select New and configure the following details, leaving all others the default value, as shown below (FIG. 3). Once you are done adding other organization-mandated details (given name, email, time zone, etc.) select Submit.

    1. User ID: Use an easy to recognize pattern here, such as int_query_fs_user or integration_query_connector.
    2. Active: Ensure this toggle is checked.
    3. Internal Integration User: Leave this UNCHECKED, for now.
    4. Identity Type: Human, change this to Machine in a later step.

    FIG. 3 - Configuring a new Integration User in the ServiceNow console.

  4. Select the user your just created, and select Set Password → Generate → Save Password (be sure to vault this generated password, you'll need it later!). Once complete, toggle the Password needs reset option and select Update. Later on when you manually reset the password, this will allow you to override the non latin-1 codec characters in the ServiceNow-generated password.

  5. Using the navigation menu, navigate to User Administration → Roles and select New on the upper-righthand of your screen. Provide a Name such as x_queryfs_role and select Submit on the upper-righthand corner as shown below (FIG. 4).

    FIG. 4 - Creating a new Role in the ServiceNow console.

  6. IMPORTANT NOTE: You will need to repeat this step multiple times for each table/meta table you need access to, in addition to the baseline requirements!! Using the navigation menu, navigate to System Security → Access Control (ACL). At the top-righthand corner select New to create a new ACL for the following meta tables: sys_db_object, sys_db_object.*, sys_dictionary, and sys_dictionary.*. You will also need to add your_table and your_table.* for other tables you'll need to federate with such as incident/incident.* or cmdb_ci_business_app/cmdb_ci_business_app.*.

    1. Type: record
    2. Operation: read
    3. Name: Your table name, such as sys_dictionary
    4. Fields: This dropdown is not labeled, it's to the immediate right of the Name dropdown as show below (FIG. 5). Leave this blank for your first table, but you'll need to change the value to * for each table as an additional ACL!
    5. Description: Not required, but you can use the following convention, if needed: Grants x_queryfs_dynamic sys_dictionary READ
    6. Requires role: In the Conditions subsection, enter the Role you created in Step 5.
    7. Once complete, select Submit and then begin the flow again. Ensure you communicate with your ServiceNow CMDB Administrators for information on table flows and meta tables.

FIG. 5 - Creating and modifying table ACLs in the ServiceNow console.

👀

Scenarios: ACLs and Tables

  1. In the case that you do not want to continue to manually create ACLs, consider adding a pre-built Role such as itil, asset, or cmdb_read to your integration user.
  2. For supporting CMDB tables that have multiple relationships, you will need to add cmdb_rel_ci, cmdb_rel_ci.*, cmdb_model, and cmdb_model.* that give access to shared relationship and model data.
  3. Business Applications require cmdb_ci_business_apps and cmdb_ci_business_apps.*.
  4. For Incidents (incident), Change Management (change_request), Problem management (problem), and Service Catalog (sc_request & sc_req_tiem) you will need to also grant access to task which is the parent for all work records and gives access to shared/common fields.
  5. Device CIs: cmdb_ci_computer.
  6. Physical devices: cmdb_ci_hardware.

Be sure to communicate with your internal ServiceNow CMDB Administrators to determine the best layout of ACLs or blend of pre-built roles to use.

  1. Navigate back to System Security → Users and Groups → Users and select the integration user created in Step 3. Scroll down to the Related Links section, select the Roles tab, and select Edit... on the righthand side of the panel to add a new Role, as shown below (FIG. 6).

    FIG. 6 - Navigating to the Role assignment panel for a User in the ServiceNow console.

  2. Enter the name of your Role on the left-hand panel on this screen, select the role, and then select the > button. You can add additional built-in Roles, and select Save when you are satisfied as shown below (FIG. 7).

    FIG. 7 - Using the Role selector widget to assign new Roles to a user in the ServiceNow console.

  3. Using the navigation pane, navigate to System OAuth → Inbound Integrations. On the top-righthand side of the screen select New integration and select OAuth - Resource owner password credential grant as shown below (FIG. 8).

    FIG. 8 - Creating a new OAuth integration client in the ServiceNow console.

  4. Provide a Name and ensure that you create your own complex passphrase to use as the Client secret that uses characters from the latin-1 codec. In the Auth scopes (optional) subsection, add a useraccount Auth Scope for the Table API as shown below (FIG. 9). When complete, select Save.

    FIG. 9 - Final configuration of the OAuth Client in the ServiceNow console.

  5. Finally, login to your Integration user and reset the password to one that is compliant and supported by the latin-1 codec. As a reminder, SAFE CHARACTERS ARE PRINTABLE ASCII, CONTROL CHARACTERS, AND BASIC WESTERN EUROPEAN ACCENTS (0xA0–0xBF and 0xC0–0xFF).

  6. (OPTIONAL) For governance purposes, log back in with your Admin user, and set the integration user toggle properly and change their type to Machine in the User table.

To learn how to configure a ServiceNow Connector, proceed to the next section, ensure you have vaulted your Username, Password, Client ID, and Client Secret for usage in the Connector configuration.

👍

On NHI security

NHI - or, Non-Human Identities - such as your integration user password AND OAuth Client Secret are extremely sensitive, especially with the READ ACLs and Table API Scope. Query securely stores the Client Secret in a dedicated AWS Secrets Manager Secret per Connector per Tenant.

Every copy is stored as securely as each other with minimum necessary permissions that only allows the specific piece of serverless infrastructure to retrieve the secret, it is never cached or persisted outside of the Secret. This does require you to continue to provide the credentials to each Connector, but they're all secured the same, and isolated from one another.

Setting up the ServiceNow Connector

Use the following steps to create a new Query Federated Search Connector for ServiceNow.

  1. Navigate to the Connectors page, select Add Connector, and selectServiceNow from the IT Service Management category as shown below (FIG. 10). You can also search for ServiceNow using the search bar in the Add Connector page.

    FIG. 10 - Locating the ServiceNow Connector in the Query Security Data Mesh console.

  2. In the Configure Connector tab, add the following detail as shown below (FIG. 11):

    1. Connector Alias Name: The human-readable name you want to give to this connector, typically this should denote the source table name and any other information you wish to convey.
    2. ServiceNow URL: The base URL of your ServiceNow instance, such as https://dev111222.service-now.com.
    3. Username: The User ID of your integration user, created in Step 3 of the Prerequisites section.
    4. Password: The latin-1 compatible password for your integration user, created in Step 11 of the Prerequisites section.
    5. Client ID: The Client ID for your OAuth Client, created in Step 10 of the Prerequisites section.
    6. Client Secret: The Client Secret for your OAuth Client, created in Step 10 of the Prerequisites section.
    7. Table Name: The name of your ServiceNow table you want to search against, such as incidents, internal_users, or cmdb_ci_business_apps.

    FIG. 11 - Configuring the parameters for the ServiceNow Connector in the Query Security Data Mesh console.

  3. Select Save to save and activate the Connector.

  4. Select Test Connection from the bottom-right of the connection pane to ensure the following conditions

    1. Your user exists, and can be logged in with successfully.
    2. Your OAuth Client is properly configured for Password flow.
    3. Your OAuth Client has the proper scopes.
    4. The table you provided exists.
    5. You have the correct ACLs within your Role for the table you provided.
    6. A sample of data and the metadata/structure for the table can be retrieved.

  5. Finally, proceed to the Preview/Import Fields section to begin the Configure Schema process.

You will now see ServiceNow added as an available Connector within the Query Search and Query Summary Insights UI.

Querying ServiceNow Connectors

Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for INTEGRATION are enabled, navigate to the IT Service Management section of the Selected Connectors dropdown and ensure that your specified ServiceNow Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 12).

FIG. 12 - Connector picker for ServiceNow in the Query Security Data Mesh console.

The Entities (Observables) and Events you will be able to search determine on how you mapped your data in Configure Schema against a given ServiceNow table. For more information about the QDM/OCSF schema itself refer to the About the Query Data Model section of the Query docs, you can also view the Categories, Events, and Objects themselves.

Resources

Troubleshooting Steps

  • Ensure that your Integration User is ACTIVE in ServiceNow, and not locked out or deactivated.
  • Consider rolling over the password, and ensure that latin-1 code compatible characters are used, stick with ASCII characters for the utmost safety.
  • Ensure your Integration User is associated with a custom Role with ACL grants, or with built-in ServiceNow roles.
  • Ensure any Custom role has two pairs of record ACLs that give READ permissions per table name, e.g., cmdb_ci_business_app and cmdb_ci_business_app.*.
  • Ensure that you created a Password-flow OAuth Client.
  • Ensure that your OAuth Client Secret is compatible with the latin-1 codec and has not expired.
  • Ensure that a useraccount Scope for the Table API has been added with your OAuth Client.
  • Ensure that you have all ACLs for meta tables and relationships with tables you wish to query, especially for custom CIs.
  • Ensure that you provided a valid table.
  • Ensure that there not any superseded ACLs or other security controls prevented table/field level access.

If you have exhausted the above Troubleshooting list, please contact your designated Query Sales Engineer or Customer Success Manager. If you are using a free tenant, please contact Query Customer Success via the Support email in the Help section, or via Intercom within your tenant.

Updated about 10 hours ago