Integration Details

ThreatQuotient provides the following details for this integration:

Introduction

The ServiceNow app is an integration that lives within the ServiceNow Marketplace and enables users to query the ThreatQ directly from the ServiceNow UI. This application has been certified by ServiceNow and is developed within their platform framework.

The current integration between ThreatQ and ServiceNow enables users to import ServiceNow Observables/Security Incidents into ThreatQ as Indicators/Security Events. This process is initiated by a ThreatQ custom connector and the data flow for this integration is one-sided and flows from ServiceNow → ThreatQ.

This integration is an inverse of the existing capabilities and is initiated by ServiceNow. The data flow for this application is in the opposite direction and flows from ThreatQ → ServiceNow.

All the calls will be made via a MID server when the On-premises deployment checkbox is checked and the MID server is selected.  See the Configuration chapter for more details.  

Prerequisites

Review the following requirements before attempting to install the app.  

Permissions and Roles

The following ServiceNow role and the permissions that are required to install the application and to use it to view and manage the vulnerability integration on ServiceNow.

ServiceNow Required Plugins

The Threat Intelligence and Security Incident Response ServiceNow plugins are required by app and must be installed and activated.

To install this plugins:

1. Log into your instance with your user credentials.
2. Verify you have the system administrator (admin) role.
3. Navigate to System Definition -> Plugins in your instance.
4. Locate and still both plugins, Threat Intelligence and Security Incident Response, using the search.
   
   
   
   

MID Server Installation

Complete steps on setting up the MID server can be found on the ServiceNow Product Documentation site: 

https://docs.servicenow.com/bundle/vancouver-servicenow-platform/page/ product/mid-server/concept/mid-server-installation.html

OAuth Client ID and Client Secret

The ServiceNow App requires you to enter your OAuth Client ID and OAuth Client Secret when configuring the app.  You can generate both using the steps below.  

You can also use the steps below to view existing credentials by using an existing integration name for the --name flag. 

ThreatQ v6 Steps

1. SSH to your ThreatQ installation.
2. Create a new client id and client secret password using the following command:
   kubectl exec --namespace threatq --stdin --tty deployment/api-schedule-run -- ./artisan threatq:oauth2-client --name="Custom Integration"

   You should see output for the new custom integration user:

   session_timeout_minutes: 1440
   name: Custom Integration
   type: private
   client_id: ntdjzwe3mduyyjqxyjdiyza5mzyxmtkx
   client_secret: YThlOTBlZjM0YTYxNWM1YjVkODdmMTdjNGY5MzZkYTg4M2RmYmRiZGJmNjk1OTRm
   updated_at: 2020-01-14 14:03:27
   created_at: 2020-01-14 14:03:27

   Be sure to generate Private Type credentials. Public Types will only generate Client ID and not a Client Secret. You can add a --type private flag to the command to ensure a Private Type is generated.

3. Copy the Client ID and Secret to a safe location to use when configuring the integration.   

ThreatQ v5 Steps 

1. SSH to your ThreatQ installation.  
2. Navigate to the api directory:
   cd /var/www/api
3. Create a OAuth Client ID and Secret using the following command:
   php artisan threatq:oauth2-client --name <ServiceNowApp>

   Example Output:

   php artisan threatq:oauth2-client --name ServiceNowApp
   session_timeout_minutes: 1440
   name: ServiceNowApp
   type: private
   client_id: njnjm2qxmddjy2flmzkxmziyzgy5n2uy
   client_secret: NmFkY2FiMTZhY2UwYjA5ZGFjZjUyOGQ2ZDhjOWRlMzYwOTFiNjcxNzVkNTE4NmU5
   updated_at: 2022-01-06 02:03:04
   created_at: 2022-01-06 02:03:04
   id: 19
   

   Be sure to generate Private Type credentials. Public Types will only generate Client ID and not a Client Secret. You can add a --type private flag to the command to ensure a Private Type is generated.

4. Copy the Client ID and Secret to a safe location to use when configuring the integration.   

Installation

Within the ServiceNow interface:

1. Use the Filter navigator and navigate to System Applications - ServiceNow Store.
2. Search for ThreatQ within the Store Application and then click the Install button.
   
   

Configuration

Within the ServiceNow interface:

1. Click Security Operations >>Integration Configuration after the application has been installed.
2. Click on the Configure button for the ThreatQ for Security Operations tile.  
   
   
3. Complete the following configuration fields:

   Field	Description
   ThreatQ Hostname	Your ThreatQ instance hostname or IP.
   On Premises Deployment	Enable this field for On Premise deployments.
   MID Server	If using an On-Premise deployment - select a valid MID Server. The Mid Server must be up and running when doing this and be accessible by the On-Premise deployment.
   OAuth Client ID	This is the OAuth Client ID you generated for use with this integration.  See the Prerequisites chapter for steps on how to generate or retrieve your OAuth Client ID for this integration.
   OAuth Client Secret	This is the OAuth Client Secret associated with the OAuth Client ID above.  See the Prerequisites chapter for steps on how to generate or retrieve your OAuth Client Secret for this integration.
   Malicious Finding Threshold	Enter the threshold value based off of which indicators having a score equal to or higher than this number will be labeled as malicious.
   Attributes	Specify comma separated ThreatQ attributes names which need to be fetched for indicator. To get a list of the attributes in ThreatQ, navigate to Settings > Object Management > Attribute Management.
   Object Properties	Specify comma separated ThreatQ properties names which need to be fetched for indicator. The property names for the enriched indicator are: Type, Status, Score, Sources, Tags. Additionally, relationships can also be ingested from ThreatQ by specifying their names: Adversaries, Asset, Attack Pattern, Campaign, Course of Action, Exploit Target, Events, Identity, Incident, Intrusion Set, Malware, Signatures, Type, TTP, Tool, Vulnerability
   TQ Attribute Location	Specify the table where you want to save each indicator’s attributes.  Options include either Threat Lookup Results or Observable Enrichment Results.

   

4. Click on Submit.

Usage

The following section will describe the steps required to create a security incident, access threat lookup results, and view observable enrichment results.

Creating a Security Incident

1. Create a new Security Incident.
   
   
2. Give the Security Incident a short description.
   
   
3. Add observables to the Security Incident.
   
   
   
   
4. Click on Submit and wait for automatic threat lookup activity to complete.
   
   You can see the new observables when you click Show IoC.
   
   

ThreatQ Lookup

The steps below are for performing manual and auto Threat Lookups.  

Manual Threat Lookup

The Threat lookup is performed to find if any observable is malicious or not.

Performing a Manual Threat Lookup:

1. Navigate to Threat Intelligence > Observables.
2. Click on any observable of type IP, URL or Hash and then click on the Run Observable Enrichment option under the Related Links heading.
   
   

   A pop-up window will open.

3. Select ThreatQ Threat Lookup and click on Submit.
   
   
4. The lookup will start and you will see lookup results, once the process is complete, under the Threat Lookup Results section.

   Threat lookup on the same observable from ThreatQ will be performed once in 24 hours only.

5. To view the Threat Lookup Results,  open the Observable and scroll down to see the Threat Lookup Results record created for the observable.
   
   
6. Open the Threat Lookup Results record to view the details of lookup.
7. From the top left, click on the  icon > View > ThreatQ to view the details of the observable.
   
   
   
   
   
   

   ThreatQ Comments will not be populated in worknotes if enrichment is executed from an observable table.
   
   To avoid duplicity, the value of created_at is ingested in the First Found field of the Threat Lookup Result table.

Auto Threat Lookup

Auto Threat Lookup can be performed on an observable by attaching to a security incident.

Performing Auto Threat Lookup:

1. Navigate to Security Incident > Incidents > Show All Incidents.
   
   
2. Click on the security incident that the observable is linked to and then click on Show IOC under the Related Links section.
   
   
3. Click New, located under the Associated Observables section, to create a new observable.  Link the observable to the security incident or click Edit to add links an existing observable.
   
   
   
   

   Once the observable is linked to the incident, auto threat lookup is started.
   
   

   Worknotes will be generated in the Incident Details tab.
   
   Threat Lookup Results can also be accessed via the ThreatQ Enrichment tab.
   
   

4. Open the threat lookup result and click on the  icon, located to the top left, and select View > ThreatQ to view the details of the observable.
   
   
   
   
   
   
   

   If there are any ThreatQ comments for the observable then worknotes will be updated with ThreatQ comments.
   
   
   
   To avoid duplicity, the value of created_at is ingested in the First Found field of the Threat Lookup Result table.

Observable Enrichment

The following steps will are performing manual and auto observable enrichment.  

Manual Observable Enrichment

The Observable Enrichment is performed to fetch additional information related to the observable.

Performing Manual Observable Enrichment:

1. Navigate to Threat Intelligence > Observables.
2. Click on any observable of type IP, URL or Hash and then click on the Run Observable Enrichment option under the Related Links heading.
   
   

   A pop-up window will open.

3. Select ThreatQ Threat Lookup and click on Submit.
   
   
4. The enrichment will start and you will see lookup results, once the process is complete, under the Observable Enrichment Results section.

   Observable enrichment on the same observable from Threat will be performed once in 24 hours only. Threat Lookup would also get performed for the observable even if Observable Enrichment Results is the provided input in TQ Attribute Locations.

5. To view the Observable Enrichment Results, open the Observable and scroll down to locate the Observable Enrichment Results record created for the observable.
   
   
6. Open the Observable Enrichment Results record to view the details of the lookup.
7. From the top left, click on the hamburger icon > View > ThreatQ to view the details of the observable.
   
   
   
   
   
   
   

   ThreatQ Comments will not be populated in worknotes if enrichment is executed from an observable table.

Auto Observable Enrichment

Auto Observable Enrichment can be performed on an observable by attaching it to a security incident.

Performing Auto Observable Enrichment:

1. Navigate to Security Incident > Incidents > Show All Incidents.
   
   
2. Click on the security incident that the observable is linked to and then click on Show IOC under the Related Links section.
   
   
3. Click New, located under the Associated Observables section, to create a new observable.  Link the observable to the security incident or click Edit to add links an existing observable.
   
   
   

   Once the observable is linked to the incident, auto threat lookup is started.
   
   

   Worknotes will be generated in the Incident Details tab.
   
   Threat Lookup Results can also be accessed via the ThreatQ Enrichment tab.
   
   

4. Open the observable enrichment results and click on the hamburger icon, located to the top left, and select View > ThreatQ to view the details of the observable.
   
   
   
   
   

   If there are any ThreatQ comments for the observable then worknotes will be updated with ThreatQ comments.

   

Troubleshooting

Increase Field of Input Field

The default max for characters used in object properties and attribute fields is 200.  The steps below detail how to increase that limit.

1. Open the sn_sec_core_integration_item_config table using the sn_sec_core_integration_item_config.list command in the navigation panel.
2. Click on the  icon on the left side and open Configure > Table.
3. Click on the Here link if you receive the following message: "This record is in the Global application, but ThreatQ for Security Operations is the current application. To edit this record click here." 
4. Search for the value named column in the columns list provided in the columns tab.
5. Update the Max Length to 500 or the required length based on your data for the value field.
6. Click on the Update.

Application Logs

1. Navigate to System Logs -> All.
   
   
2. To display application-specific logs apply the following filter displayed in the image below.
   
   

Upgrading Application

Perform the following steps when upgrading the application from a previous version.  

The user needs to reconfigure credentials in the Integration Tile after the application has been upgraded.

Data that has already been enriched wouldn't have values in the newly created fields. These can be seen data in the Default View.

1. Log in to the instance.
2. Navigate to System Applications > All Available Applications > All.
3. Find the application with the filter criteria and search bar.
4. Next to the application listing, select the version to install.
5. Click Update.

   Existing workflow activity will not be affected by the Upgrade process.

Known Issues / Limitations

• The Hash Observable Type record in the observable enrichment under the ThreatQ Enrichment tab will not get populated in the Security Incident.
• You might see error logs regarding column type conversion for the ThreatQ Score field.  Please ignore these, they will not impact the integration.  We have shipped an alternative column with the same name and type as an integer and deprecated the previously used column.

Change Log

• Version 1.4.0
  • Migrated the workflow to flow designer.
  • Added support for Washington DC and Xanadu releases.
• Version 1.3.0
  • Added support for On-Premise deployment using the ServiceNow MID server.
  • Added compatibility for the Vancouver version.
  • Resolved an issue with the conversion score (string to integer).
  • Added a new Known Issue / Limitation entry regarding possible error logs regarding column type conversion for the ThreatQ Score field.  
• Version 1.2.0
  • Added to the app configuration page the ability to enter a comma-separated list of observables relationships to be ingested from ThreatQ: Adversaries, Asset, Attack Pattern, Campaign, Course of Action, Exploit Target, Events, Identity, Incident, Intrusion Set, Malware, Signatures, Type, TTP, Tool, Vulnerability.
  • Added to the app configuration page the ability to enter a comma-separated list of ThreatQ attribute names to be ingested during the enrichment.
  • Added to the app configuration page the ability to enter a comma-separated list of observable properties’ names to be ingested from ThreatQ during enrichment: Type, Status, Score, Sources, Tags.
  • Added separate columns in ServiceNow to store each object artifact (Tags, Comments, Description, Status, Attributes, Score, Sources and relationships) that has been ingested from ThreatQ.
  • Updated the format of the ThreatQ score from string to integer.
  • Updated the format of the Created Date and Modified Date from string to a date format.
  • Validated the app for the Utah release.
  • Updated minimum ThreatQ version to 5.16.0.
• Version 1.1.0
  • Added new Oauth configuration option, TQ Attributes Location, that lets you specify the table where indicator attributes are saved.  
  • Validated app for San Diego and Tokyo.  
• Version 1.0.9
  • Initial release