Integration Details

ThreatQuotient provides the following details for this integration:

Introduction

ThreatQ v6 Users – while the connector’s overall operation remains the same, installation and usage commands for ThreatQ v6 users will differ from what is listed in this guide. See the Installing Custom Connectors in ThreatQ v6 and Installing Custom Connectors on Another Instance topics for additional information.

Resilient Connector for ThreatQuotient allows new context from ThreatQ to be exported to your Resilient instance. It has the ability to push new indicators and comments from updated Resilient incidents in ThreatQ to Resilient as artifacts and comments, respectively.

The Resilient Connector is a component of the Resilient App and must be used along with the Resilient CTS and Resilient Functions integrations.   

Prerequisites

Review the following requirements before attempting to install the connector.  

Time Zone

The time zone steps are for ThreatQ v5 only.  ThreatQ v6 users should skip these steps.  

You should ensure all ThreatQ devices are set to the correct time, time zone, and date (UTC is recommended), and using a clock source available to all.

To identify which time zone is closest to your present location, use the timedatectl command with the list-timezones command line option.

For example, enter the following command to list all available time zones in Europe:

Enter the following command, as root, to change the time zone to UTC:

PIP.conf

Prior to ThreatQ version 4.10, you were required to modify your system's pip.conf to use the ThreatQ integrations python repo, also known as DevPi. This functionality was made available upon an initial install of 4.10.  If you have upgraded to 4.10 from a previous version, you will need to modify the pip.conf on your environment to the following (replacing username and password with your information).

[global]
   index-url = https://system-updates.threatq.com/pypi
   extra-index-url = https://<username>:<password>@extensions.threatq.com/threatq/integrations
                     https://<username>:<password>@extensions.threatq.com/threatq/sdk

Integration Dependencies

The integration must be installed in a python 3.6 environment.

The following is a list of required dependencies for the integration.  These dependencies are downloaded and installed during the installation process.  If you are an Air Gapped Data Sync (AGDS) user, or run an instance that cannot connect to network services outside of your infrastructure, you will need to download and install these dependencies separately as the integration will not be able to download them during the install process.

Items listed in bold are pinned to a specific version.  In these cases, you should download the version specified to ensure proper function of the integration.

Installation

The following provides you with steps on installing a Python 3 Virtual Environment and installing the connector.

Creating a Python 3.6 Virtual Environment  

Run the following commands to create the virtual environment:

Proceed to Installing the Connector.

Installing the Connector

Upgrading Users - Review the Change Log for updates to configuration parameters before updating.  If there are changes to the configuration file (new/removed parameters), you must first delete the previous version's configuration file before proceeding with the install steps listed below.  Failure to delete the previous configuration file will result in the connector failing.

1. Navigate to the ThreatQ Marketplace and download the .whl file for the integration.
2. Activate the virtual environment if you haven't already:
   source /opt/tqvenv/<environment_name>/bin/activate
3. Transfer the whl file to the /tmp directory on your ThreatQ instance.  
4. Install the connector on your ThreatQ instance:
   pip install /tmp/tq_conn_resilient-<version>-py3-none-any.whl 

   A driver called tq-conn-tq-conn-resilient will be installed.   After installing, a script stub will appear in /opt/tqvenv/<environment_name>/bin/tq-conn-tq-conn-resilient .

5. Once the application has been installed, a directory structure must be created for all configuration, logs and files, using the mkdir -p command. Use the commands below to create the required directories:
   mkdir -p /etc/tq_labs/
   mkdir -p /var/log/tq_labs/
6. Perform an initial run using the following command:
   /opt/tqvenv/<environment_name>/bin/tq-conn-resilient -ll /var/log/tq_labs/ -c /etc/tq_labs/ -v3
7. Enter the following parameters when prompted:

   Parameter	Description
   ThreatQ Host	This is the host of the ThreatQ instance, either the IP Address or Hostname as resolvable by ThreatQ.
   ThreatQ Client ID	This is the OAuth id that can be found at Settings Gear → User Management → API details within the user’s details.
   ThreatQ Username	This is the Email Address doe the user in the ThreatQ System for integrations.
   ThreatQ Password	The password for the above ThreatQ account.

   Example Output

   /opt/tqvenv/<environment_name>/bin/tq-conn-resilient -ll /var/log/tq_labs/ -c /etc/tq_labs/ -v3
   ThreatQ Host: <ThreatQ Host IP or Hostname> 
   ThreatQ Client ID: <ClientID> 
   ThreatQ Username: <EMAIL ADDRESS> 
   ThreatQ Password: <PASSWORD> 
   Connector configured. Set information in UI

You will still need to configure and then enable the connector.

Configuration

ThreatQuotient does not issue API keys for third-party vendors. Contact the specific vendor to obtain API keys and other integration-related credentials.

To configure the integration:

1. Navigate to your integrations management page in ThreatQ.
2. Select the Labs option from the Category dropdown (optional).
3. Click on the integration entry to open its details page.
4. Enter the following parameters under the Configuration tab:

   Parameter	Description
   Resilient Host	The hostname or IP address of your Resilient instance.
   Resilient Username	The email you will use authenticate with the Resilient API.
   Resilient Password	The password you will use authenticate with the Resilient API.
   Resilient Organization	Your Organization within your Resilient instance.
   Resilient Certificate Path	he path to your Resilient certificate. This field is optional. If left blank, the SSL will not be verified. See the Generating a Certificate section for instructions on how generate a certificate. If using this method, verify that the certificate is accessible to the connector.
   Attribute to Custom Field Mapping	Map ThreatQ attributes to Custom Fields in Resilient. Each mapping must be on its own line and is in a key=value format. Confidence=confidence_level The Resilient Custom Field name must be the programmatic API name. See the Customization Settings section within your Resilient instance for more details.
   ThreatQ to Custom Field Mapping	Map ThreatQ objects to Custom Fields in Resilient. Each mapping must be on its own line and is in a key=value format. TTP=mitre_technique_name The Resilient Custom Field name must be the programmatic API name. See the Customization Settings section within your Resilient instance for more details.

5. Review any additional settings, make any changes if needed, and click on Save.
6. Click on the toggle switch, located above the Additional Information section, to enable it.

Usage

Use the following command to execute the driver:

Include the -n flag in the command above if you renamed the connector. See the Known Issues / Limitations section for more details.

Command Line Arguments

This connector supports the following custom command line arguments:

CRON

Automatic CRON configuration has been removed from this script. To run this script on a recurring basis, use CRON or some other jobs scheduler. The argument in the CRON script must specify the config and log locations.

Add an entry to your Linux crontab to execute the connector at a recurring interval. Depending on how quickly you need updates, this can be run multiple times a day (no more than once an hour) or a few times a week.

In the example below, the command will execute the connector every two hours.

1. Log into your ThreatQ host via a CLI terminal session.
2. Enter the following command:
   crontab -e

   This will enable the editing of the crontab, using vi. Depending on how often you wish the cronjob to run, you will need to adjust the time to suit the environment.

3. Enter the commands below:

   Every 2 Hours Example

   0 */2 * * * /opt/tqvenv/<environment_name>/bin/tq-conn-tq-conn-resilient -c /etc/tq_labs/ -ll /var/log/tq_labs/ -v3  
4. Save and exit CRON.

Generating a Certificate

Use the following command to generate a certificate to use with the connector:

The full path of the generated .pem file should be used as the certificate path in the connector configuration

ThreatQ Mapping

The table below illustrates how ThreatQ threat intel is mapped when it is submitted to your Resilient instance.  

Known Issues / Limitations

• Disabling and re-enabling the connector in the ThreatQ UI, after installing the connector, will result in an error with the connector failing to enable.  If you encounter this issue, the connector must be re-installed and renamed using the -n flag when first initializing the connector in step 3 of the Resilient Connector process.
  
  Performing Initial Run with New Name Example Command
  tq-conn-resilient /path/to/config/directory/ -ll /path/to/log/directory/ -v3 VERBOSITY_LEVEL -n "Resilient2"

Change Log

• Version v1.2.0
  • Added Python3 support
  • Updated Threat Library Code to reflect updates in the ThreatQ platform
• Version v1.1.1
  • Added support for syncing Malware Objects as Malware Family/Variant artifacts
  • Added support for syncing Attributes from ThreatQ to Custom Fields in Resilient
  • Added support for syncing Objects from ThreatQ to Custom Fields in Resilient
  • Updated documentation with Context Support Section
  • Updated documentation with new configuration fields
  • Added version 4.0.2 to the configparser requirement in setup.py
• Version 1.0.0
  • Added the ability to sync new indicators to Resilient
  • Added the ability to sync new comments to Resilient