> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.strix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ServiceNow Integration

> Connect Strix to ServiceNow to export vulnerabilities as Incident or Task records

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

Strix connects natively to ServiceNow. Strix can export the vulnerabilities that scans and PR reviews find as records on the ServiceNow `incident` table or the `task` table. You select the record type when you connect. Strix posts status changes and comments to those records as work notes. Every 5 minutes, Strix reads the state of the linked records and updates the Strix issues. This page describes the setup, the two authentication methods, the permissions that Strix needs, the data that Strix sends, and the disconnect procedure.

## Overview

|                  |                                                                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integration type | Native ServiceNow Table API client. No third-party middleware in the data path                                                                                               |
| Direction        | Two-way. Strix creates and updates records. Strix reads the state of linked records every 5 minutes, see [What data flows where](#what-data-flows-where)                     |
| Record type      | `incident` (default) or `task`. You select the record type when you connect. The `task` table needs one extra ACL, see [Use the Task record type](#use-the-task-record-type) |
| Authentication   | OAuth 2.0 Client Credentials (recommended) or username and password of an integration user                                                                                   |
| Who can connect  | Strix organization **admins** only                                                                                                                                           |
| Scope of access  | One ServiceNow instance for each Strix organization                                                                                                                          |
| Destination      | A ServiceNow assignment group                                                                                                                                                |

## Before you start

Strix needs a ServiceNow identity that has the `itil` role. The `itil` role permits the identity to read the `sys_user_group` table and to create and update records on the `incident` table. On a standard instance, the `itil` role cannot create records on the base `task` table. If you want Task records, a ServiceNow admin must add one ACL, see [Use the Task record type](#use-the-task-record-type). Do not use a personal account.

Select one authentication method:

|                           | OAuth client (recommended)                                                                 | Username and password                       |
| ------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------- |
| What you paste into Strix | Client ID and client secret                                                                | Username and password                       |
| ServiceNow identity       | The **OAuth Application User** of the OAuth API endpoint                                   | The integration user                        |
| Tokens                    | Strix requests short-lived bearer tokens from your instance. Strix never stores a password | Strix sends the password with every request |
| ServiceNow release        | Washington DC or later, with the Client Credentials grant enabled                          | Any release                                 |

### Option A: Create an OAuth API endpoint (recommended)

A ServiceNow administrator with the `admin` role does these steps in your instance. The Strix connect dialog shows the same steps. After you enter the instance URL in the dialog, each step links into your instance.

The steps differ by ServiceNow release. Do the steps for your release only.

<Tabs>
  <Tab title="Zurich or later">
    1. Set the system property `glide.oauth.inbound.client.credential.grant_type.enabled` to `true`. Open `sys_properties.list` in the filter navigator and search for the property. If the property does not exist, open this URL on your instance to get a prefilled form, then click **Submit**:

       ```text theme={null}
       https://<instance>.service-now.com/sys_properties.do?sys_id=-1&sysparm_query=name=glide.oauth.inbound.client.credential.grant_type.enabled^type=boolean^value=true
       ```

       Without this property, token requests fail with `access_denied`.
    2. Create a service account user. The **Create a user** link in the Strix dialog opens a prefilled form. If you open `sys_user.do?sys_id=-1` yourself, enter a **User ID**, for example `strix-integration`, a **First name**, and a **Last name**. Set **Identity type** to **Machine**. Select **Internal Integration User**. The user does not need a password. Right-click the form header and click **Save**, not **Submit**, so the record stays open.
    3. In the **Roles** list at the bottom of the saved user, click **Edit…**, add `itil`, and click **Save**.
    4. Go to **System OAuth → Application Registry** and click **New**. ServiceNow rejects records that are inserted directly into the `oauth_entity` table, so always start from **New**.
    5. Select **New Inbound Integration Experience → New Integration → OAuth – Client credentials grant**. You can also start from **Machine Identity Console → Inbound integrations → New integration**.
    6. Set **Name** and **Provider name** to `Strix`. Set **OAuth application user** to the user from step 2. The picker shows only users that have a first name and a last name.
    7. Under **Scope validation settings**, clear **Allow access only to APIs in selected scope**. Do not add an auth scope. Leave **Advanced options** unchanged. Click **Save**.
    8. Copy the **Client ID** and the **Client secret**. The eye icon shows the secret.
  </Tab>

  <Tab title="Washington DC to Yokohama">
    1. Set the system property `glide.oauth.inbound.client.credential.grant_type.enabled` to `true`. Open `sys_properties.list` in the filter navigator and search for the property. If the property does not exist, open this URL on your instance to get a prefilled form, then click **Submit**:

       ```text theme={null}
       https://<instance>.service-now.com/sys_properties.do?sys_id=-1&sysparm_query=name=glide.oauth.inbound.client.credential.grant_type.enabled^type=boolean^value=true
       ```

       Without this property, token requests fail with `access_denied`.
    2. Create a service account user. The **Create a user** link in the Strix dialog opens a prefilled form. If you open `sys_user.do?sys_id=-1` yourself, enter a **User ID**, for example `strix-integration`, a **First name**, and a **Last name**. Select **Web service access only**. If the form shows **Internal Integration User**, select it. The user does not need a password. Right-click the form header and click **Save**, not **Submit**, so the record stays open.
    3. In the **Roles** list at the bottom of the saved user, click **Edit…**, add `itil`, and click **Save**.
    4. Go to **System OAuth → Application Registry** and click **New**. ServiceNow rejects records that are inserted directly into the `oauth_entity` table, so always start from **New**.
    5. Select **Create an OAuth API endpoint for external clients**. On Yokohama, this option has the prefix **\[Deprecated UI]**. The classic form is the correct path for these releases.
    6. Set **Name** to `Strix`. Leave **Client Secret** and **Redirect URL** empty. ServiceNow generates the secret. Do not add an auth scope. Click **Submit**.
    7. Open the saved record. If the form does not show the **OAuth Application User** field, right-click the form header and select **Configure → Form Layout**, then add the field.
    8. Set **OAuth Application User** to the user from step 2. Click **Update**.
    9. Copy the **Client ID**. Click the padlock on **Client Secret** and copy the secret.
  </Tab>
</Tabs>

The Client Credentials grant is a machine-to-machine flow. It does not use a redirect URL, a login URL, or a refresh token. Every request that Strix makes runs as the OAuth application user, so that user's roles control the access.

### Option B: Create an integration user

Use this option if your instance does not support the Client Credentials grant.

1. Create a user. The **Create a user** link in the Strix dialog opens a prefilled form. If you open `sys_user.do?sys_id=-1` yourself, enter a **User ID**, for example `strix-integration`, a **First name**, and a **Last name**. On Zurich or later, set **Identity type** to **Machine**. On earlier releases, select **Web service access only**. Click **Set Password**, generate a password, and copy it. Right-click the form header and click **Save**, not **Submit**, so the record stays open.
2. In the **Roles** list at the bottom of the saved user, click **Edit…**, add `itil`, and click **Save**.

## Setup

1. In Strix, go to **Settings → Integrations** and click **Connect** on the ServiceNow card. You must be an organization admin, and your plan must include ticketing integrations.
2. Enter the instance URL or hostname, for example `acme.service-now.com`. Strix uses HTTPS. The setup links below the authentication choice open in your instance after you enter the URL.
3. Under **Authentication**, select **OAuth client** or **Username and password**. The default is **OAuth client**.
4. Enter the client ID and the client secret, or the username and the password.
5. Select the **record type**. **Incident** creates ITSM incidents on the `incident` table. **Task** creates generic work items on the `task` table. The default is **Incident**. If you select **Task**, Strix shows the ACL steps from [Use the Task record type](#use-the-task-record-type). Click **Connect**.
6. Strix verifies the credentials before it stores them. For an OAuth client, Strix first requests a token from `/oauth_token.do`. Then Strix reads the selected record table and the `sys_user_group` table. If the verification fails, Strix shows the reason and does not store the credentials.
7. In Strix, select a **default assignment group** as the export destination. You can also enable **auto-sync** with a minimum severity. Auto-sync exports new findings automatically.

You can also connect through the API. With an OAuth client:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/integrations/servicenow/connect" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_url": "https://acme.service-now.com",
    "auth_method": "oauth_client_credentials",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "record_type": "incident"
  }'
```

With an integration user:

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/integrations/servicenow/connect" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_url": "https://acme.service-now.com",
    "auth_method": "basic",
    "username": "strix-integration",
    "password": "<PASSWORD>",
    "record_type": "incident"
  }'
```

**Required scope:** `integrations:write`

The `auth_method` field is optional. Permitted values are `oauth_client_credentials` and `basic`. If you omit `auth_method`, Strix uses `basic` when the body has `username` and no `client_id`. In all other cases Strix uses `oauth_client_credentials`.

The `record_type` field is optional. Permitted values are `incident` and `task`. The default is `incident`.

If you connect the same organization to a different instance URL, Strix clears the default assignment group and the links between vulnerabilities and records. If you connect with a different record type, Strix clears the links between vulnerabilities and records but keeps the default assignment group. If you only change the credentials or the authentication method for the same instance, Strix keeps the settings and the links. To change the authentication method, connect again.

### Change the record type

You can change the record type after you connect. In Strix, open the ServiceNow card and click **Settings**. Under **Record type**, select **Incident** or **Task**. Strix saves the change immediately.

Record identifiers are specific to one table. When you change the record type, Strix removes the links between vulnerabilities and the existing records. Strix does not delete the records in ServiceNow. The next export creates a new record on the selected table.

### Use the Task record type

Most ServiceNow integrations create Incident records. Incident is the table that every ITSM instance has, with assignment groups, SLAs, and workflows in place. Strix uses Incident as the default for that reason.

Select **Task** if your team tracks security work as generic tasks. On a standard instance, the `itil` role can create Incident records but cannot create records on the base `task` table. ServiceNow rejects the insert with `ACL Exception Insert Failed due to security constraints`. A ServiceNow admin must add one create ACL. This is a one-time step.

1. In ServiceNow, open your profile menu and click **Elevate role**. Select **security\_admin** and click **OK**.
2. In Strix, select **Task** as the record type and click **Open the prefilled ACL form**. The link opens `sys_security_acl.do` in your instance with **Type** set to `record`, **Operation** set to `create`, and **Name** set to `task`. Check the three values. You can also open **System Security → Access Control (ACL)**, click **New**, and enter those three values.
3. Right-click the form header and click **Save**.
4. Under **Requires role**, click **Edit…**, add `itil`, and click **Save**.

After the ACL exists, Strix can create Task records with the same identity. Until then, an export to the `task` table fails with a message that names the missing ACL. Incident records need no extra step.

### Troubleshooting the OAuth connection

| Message from Strix                                                           | Cause                                                                                                                                                                                                                          | Action                                                                                                                                            |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| ServiceNow returned access\_denied for this OAuth client                     | ServiceNow returns the same error for a wrong client ID or secret, for a disabled Client Credentials grant, and for a missing OAuth application user                                                                           | Set `glide.oauth.inbound.client.credential.grant_type.enabled` to `true`, set the OAuth application user on the record, and copy the values again |
| ServiceNow did not issue a token for this OAuth client                       | The Client Credentials grant is not enabled, or the record has no OAuth Application User                                                                                                                                       | Do step 1 and step 6 or step 8 of Option A                                                                                                        |
| The OAuth Application User cannot read incident records or assignment groups | The service account does not have the `itil` role, or the OAuth record limits access to selected auth scopes. ServiceNow returns HTTP 200 with an empty `result` array in this case, and `X-Total-Count` shows the hidden rows | Give the service account the `itil` role. Clear **Allow access only to APIs in selected scope** and remove auth scopes                            |
| ServiceNow denied creating a Task record                                     | The base `task` table has no create ACL for the `itil` role                                                                                                                                                                    | Add the ACL from [Use the Task record type](#use-the-task-record-type), or select **Incident** as the record type                                 |

| Message from ServiceNow                                   | Cause                                                                                                        | Action                                                                                         |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `Invalid insert` on the OAuth form                        | The record was opened directly instead of through **New**                                                    | Open **Application Registry**, click **New**, and select the flow for your release             |
| **OAuth application user** shows no results               | The service account has no first name or last name                                                           | Add a first name and a last name to the user                                                   |
| `Access to unscoped api is not allowed`                   | The OAuth record limits access to selected auth scopes                                                       | Clear **Allow access only to APIs in selected scope** and remove auth scopes                   |
| `ACL Exception Insert Failed due to security constraints` | The identity has no create ACL on the selected table. With the `itil` role, this happens on the `task` table | Add the ACL from [Use the Task record type](#use-the-task-record-type), or select **Incident** |

## What data flows where

**Strix → ServiceNow** (when you export a vulnerability manually, or when auto-sync exports it):

* `short_description`: the vulnerability title, cut to 160 characters.
* `description`: severity, CVSS and CVE (when present), target, endpoint or affected file, impact, technical analysis, evidence, suggested fix or remediation steps, proof of concept, and a link back to the issue in Strix. Strix converts the Markdown to plain text.
* `impact` and `urgency` mapped from severity. ServiceNow derives the record priority from these two fields.
* `assignment_group`: the selected assignment group.
* `due_date` when an issue is snoozed.
* `state` when the Strix status changes. For `task` records, Strix maps Open to Open, In Progress to Work in Progress, On Hold to Pending, and Closed to Closed Complete. For `incident` records, Strix maps Open to New, In Progress to In Progress, On Hold to On Hold, and Closed to Resolved.
* Work notes (for example, "marked In Progress by …") when the Strix status changes.

**ServiceNow → Strix** (scheduled, every 5 minutes):

ServiceNow does not offer an API that lets a third party subscribe to record changes. Strix therefore reads the state of the linked records with the credentials that you already provided. This is the same model that Vanta and Drata use. You do not need a Business Rule, an Outbound REST Message, or a Store app.

* Strix reads only the records that it created. Strix requests the `sys_id`, `number`, `state`, `due_date`, `sys_updated_by`, and `sys_updated_on` fields.
* Strix maps the ServiceNow state to the Strix issue status. For `incident` records, Resolved, Closed, and Canceled mark the issue **fixed**. In Progress marks the issue **in progress**. New reopens a fixed issue. For `task` records, Closed Complete, Closed Incomplete, and Closed Skipped mark the issue **fixed**. Work in Progress marks the issue **in progress**. Open reopens a fixed issue.
* On Hold (`incident`) and Pending (`task`) snooze the issue until the `due_date` of the record. Without a future `due_date`, Strix leaves the issue unchanged.
* A change in ServiceNow appears in Strix within about 5 minutes. The sync is not realtime.
* Strix does not overwrite an issue that you marked **ignored** or **not affected** in Strix when the record is closed in ServiceNow.
* Strix adds a note to the issue, for example "Updated from ServiceNow — ticket INC0010005 by admin".
* When ServiceNow no longer returns a record, for example after a deletion, Strix leaves the issue unchanged.
* When ServiceNow rejects the credentials, Strix sets the integration to **reconnect required** and stops the sync until an admin reconnects.

Strix does not read comments, attachments, or user directories.

## Security

* **Admin-gated**: The connect endpoint requires an authenticated Strix org admin.
* **Credential verification**: Strix verifies the credentials against your instance before it stores them.
* **Encrypted storage**: Strix encrypts the client secret or the password with AES-256-GCM before it writes it to the database. The browser and other tenants cannot read it. The API does not return the client secret or the password.
* **Short-lived tokens**: With an OAuth client, Strix keeps the bearer token in memory only for its lifetime, 30 minutes by default. Strix requests a new token when the token expires or when ServiceNow rejects it.
* **Outbound request protection**: Strix resolves the instance host and blocks requests to private network addresses.
* **Audit trail**: The Strix audit log records the connection of the integration and the changes to the settings.

## Disconnecting

An org admin can disconnect ServiceNow at any time from **Settings → Integrations**, or through the API:

```bash theme={null}
curl -X DELETE "https://app.strix.ai/api/v1/integrations/servicenow" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `integrations:write`

The disconnect operation removes the stored credentials. Strix does not delete the records that it already created in ServiceNow. If you no longer need them, deactivate the application registry record or the integration user in ServiceNow.