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

# ServiceNow

> Connect ThreatAware to ServiceNow to sync IT assets and incident management data

## Overview

The ServiceNow integration enables ThreatAware to collect IT service management data from your ServiceNow instance, providing visibility into assets, incidents, and configuration management data.

<Info>
  **Connection Method**: API
  **Setup Time**: 15 minutes
  **Access Required**: ServiceNow Administrator account
</Info>

## Data collected

The ServiceNow integration provides:

* IT asset inventory
* Incident and change data
* Configuration management database (CMDB) records
* Service request information

## Use cases

<CardGroup cols={2}>
  <Card title="Asset Synchronization" icon="database">
    Sync IT assets between ServiceNow and ThreatAware
  </Card>

  <Card title="Incident Correlation" icon="triangle-exclamation">
    Link security incidents with IT service management tickets
  </Card>

  <Card title="Configuration Tracking" icon="cog">
    Track IT configuration changes and compliance
  </Card>

  <Card title="Change Management" icon="git">
    Monitor IT change requests and their security impact
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Access ServiceNow User Administration">
    Create a dedicated API user in ServiceNow:

    * Log in to your ServiceNow instance with administrator privileges
    * Navigate to **User Administration** > **Users** section
  </Step>

  <Step title="Create New API User">
    Add a user account for ThreatAware:

    * Click **Create New User**
    * Fill in the user details:
      * **User ID**: `threataware` or similar identifier
      * **First Name**: ThreatAware
      * **Last Name**: Integration
    * Check the **Web service access only** checkbox
      * This restricts the account to API access
      * Improves security by preventing interactive login
    * Click **Save** to create the user account
  </Step>

  <Step title="Assign Required Role">
    Configure permissions for the API user:

    * Select the newly created user from the user list
    * Navigate to the **Roles** tab
    * Add the **cmdb\_read** role
      * This grants read-only access to CMDB records
      * Sufficient for data collection by ThreatAware
    * Save the changes

    <Tip>
      The `cmdb_read` role provides read-only access to the Configuration Management Database, which is sufficient for ThreatAware integration.
    </Tip>
  </Step>

  <Step title="Set User Password">
    Create credentials for the API user:

    * While on the user record, locate the password fields
    * Set a strong password for this user
    * Copy and save the password securely for ThreatAware configuration
  </Step>

  <Step title="Configure in ThreatAware">
    Add ServiceNow credentials to ThreatAware:

    * Log in to the ThreatAware dashboard
    * Navigate to **Settings → Integrations**
    * Search for **ServiceNow** and click **Connect**
    * Fill in the required fields:
      * **Instance URL**: Your ServiceNow platform URL (e.g., `https://yourdomain.service-now.com`)
      * **Username**: `threataware` (or the User ID created in Step 2)
      * **Password**: The password set in Step 4
    * Click **Connect** to establish the integration
  </Step>

  <Step title="Verify Connection">
    Confirm successful integration:

    * Check that the integration status in ThreatAware shows **Active**
    * Wait 5-10 minutes for initial data synchronization
    * Verify ServiceNow asset data appears in ThreatAware
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="Instance URL" icon="globe">
    **Field Name**: ServiceNow Instance URL
    **Type**: String
    **Description**: The base URL of your ServiceNow instance

    Format: `https://yourdomain.service-now.com`

    Where "yourdomain" is your unique ServiceNow subdomain.

    Example: `https://acme.service-now.com`
  </Accordion>

  <Accordion title="Username" icon="user">
    **Field Name**: ServiceNow Username
    **Type**: String
    **Description**: The user ID of the API user created in ServiceNow

    Example: `threataware`

    This should be the User ID field from the user record, not the email address.
  </Accordion>

  <Accordion title="Password" icon="lock">
    **Field Name**: ServiceNow Password
    **Type**: Password (encrypted)
    **Description**: The password for the ServiceNow API user

    Set during user creation in ServiceNow.

    <Warning>
      Store this password securely in your organisation's password manager. It provides access to your ServiceNow data.
    </Warning>
  </Accordion>
</AccordionGroup>

## Verification and testing

After setup, verify the integration is working correctly:

1. **Check Integration Status**
   * Navigate to **Settings → Integrations** in ThreatAware
   * Confirm ServiceNow shows **Active** status
   * Check the last sync timestamp

2. **Verify Data Collection**
   * Wait 5-10 minutes for initial data synchronization
   * Search ThreatAware dashboard for ServiceNow asset data
   * Verify CMDB records match your ServiceNow inventory

3. **Test Queries**
   * Create a test query to filter assets by ServiceNow data
   * Verify asset details and configuration data are available

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid Credentials Error" icon="triangle-exclamation">
    **Symptoms**: Integration fails with authentication error

    **Solutions**:

    * Verify the username is the User ID, not an email address
    * Ensure the password is correct and has not expired
    * Check that the user account is active (not disabled)
    * Confirm **Web service access only** is enabled for the user
    * Try resetting the user password and updating ThreatAware
  </Accordion>

  <Accordion title="Permission Issues" icon="ban">
    **Symptoms**: Integration connects but no CMDB data appears

    **Solutions**:

    * Verify the user has the **cmdb\_read** role assigned
    * Check that the user does not have conflicting roles
    * Review the [ServiceNow API documentation](https://developer.servicenow.com/dev.do#!/reference) for required permissions
    * Add additional roles if needed for your data requirements
    * Test with an admin user to confirm data exists
  </Accordion>

  <Accordion title="Incorrect Instance URL" icon="globe">
    **Symptoms**: Integration fails to connect to the server

    **Solutions**:

    * Verify the instance URL in your browser address bar
    * Ensure it's formatted correctly: `https://yourdomain.service-now.com`
    * Check for typos or extra spaces in the URL
    * Test the URL in a browser to confirm it's accessible
    * Contact your ServiceNow administrator if URL is uncertain
  </Accordion>

  <Accordion title="Connection Timeout" icon="clock">
    **Symptoms**: Integration fails to connect or frequently times out

    **Solutions**:

    * Verify your network allows HTTPS (443) outbound access
    * Check that your ServiceNow instance is accessible from your network
    * Test the instance URL in a browser to confirm connectivity
    * Temporarily disable corporate proxy or VPN and test
    * Contact your network administrator if access is blocked
  </Accordion>

  <Accordion title="No Data After Connection" icon="database">
    **Symptoms**: Integration shows active but no asset data appears

    **Solutions**:

    * Wait up to 15 minutes for initial data synchronization
    * Verify you have assets in your ServiceNow CMDB
    * Check that the user account has CMDB read access
    * Review ThreatAware integration logs for sync errors
    * Contact ServiceNow support if CMDB data is missing
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="ServiceNow Developer Portal" icon="book" href="https://developer.servicenow.com/dev.do#!/reference">
    Official ServiceNow API and developer documentation
  </Card>

  <Card title="ServiceNow Platform Documentation" icon="browser" href="https://developer.servicenow.com/dev.do#!/reference">
    ServiceNow platform documentation and guides
  </Card>

  <Card title="ServiceNow Support" icon="life-ring" href="https://support.servicenow.com/">
    ServiceNow support and technical assistance
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **Dedicated Service Account**

  * Create a dedicated user account specifically for ThreatAware
  * Use descriptive names like "threataware" or "svc\_threataware"
  * Enable **Web service access only** for security
  * Document the account in your IT service management system
</Tip>

<Tip>
  **Credential Security**

  * Store the ServiceNow password in your organisation's password manager
  * Treat it with the same security as admin passwords
  * Periodically reset or rotate the password per your security policy
  * Monitor API usage in ServiceNow logs
  * Revoke access if the integration is no longer needed
</Tip>

<Tip>
  **Permissions Management**

  * Use the minimal **cmdb\_read** role for read-only access
  * Never grant admin or write permissions unless absolutely necessary
  * Review the [ServiceNow API documentation](https://developer.servicenow.com/dev.do#!/reference) for specific permission requirements
  * Adjust roles if ThreatAware needs additional data access
</Tip>