Integration Details

ThreatQuotient provides the following details for this integration:

Current Integration Version	2.0.1
Compatible with ThreatQ Versions	>= 4.20.0
Python Version	2.7
Support Tier	ThreatQ Supported

Introduction

The ThreatQuotient for Auto Focus Application is a unidirectional connector that pulls information from AutoFocus and uploads it into the ThreatQ instance. It pulls samples from AutoFocus, and creates events based off of them within ThreatQ. In addition, it will pull any related indicators, tags, regions, and signatures that it finds using AutoFocus' API.

Prerequisites

Review the following requirements before attempting to install the connector.  

Time Zone

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:

Integration Dependencies

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.

Dependency	Version	Notes
requests	N/A	N/A
threatqsdk	>=1.6.0	N/A
threatqcc	>=1.3.0	N/A

Installation

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. Transfer the whl file to the /tmp directory on your ThreatQ instance.  
3. Install the connector on your ThreatQ instance:
   pip install /tmp/tq_conn_auto_focus-<version>-py2-none-any.whl 

   A driver called tqAutoFocus will be installed.   After installing, a script stub will appear in tqAutoFocus.

4. 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/
5. Perform an initial run using the following command:
   tqAutoFocus -ll stdout -c /etc/tq_labs/ -v3
6. 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 of the user in the ThreatQ System for integrations.
   ThreatQ Password	The password for the above ThreatQ account.
   Status	This is the default status for objects that are created by this Integration.

   Example Output

   tqAutoFocus -ll stdout -c /etc/tq_labs/ -v3
   ThreatQ Host: <ThreatQ Host IP or Hostname> 
   ThreatQ Client ID: <ClientID> 
   ThreatQ Username: <EMAIL ADDRESS> 
   ThreatQ Password: <PASSWORD>
   Status: Review 
   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
   API Token	Your AutoFocus API Token.
   File Type	Optional - the filetype name if you want to pull a specific filetype (e.g. DLL, Android APK, PE, etc.) By default, to maintain the original functionality of the code, samples with  Android APK file type are excluded from the sample search.
   First Run Historical Timeframe (days)	Specify how many days in the past you want to look and download samples.  The larger the number, the longer the integration run will take the first time (700 samples will take an estimated 45-60 minutes).

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:

Command Line Arguments

This connector supports the following custom command line arguments:

Argument	Description
-h, --help	Review all additional options and their descriptions.
-ll LOGLOCATION, --loglocation LOGLOCATION	Sets the logging location for the connector. The location should exist and be writable by the current. A special value of 'stdout' means to log to the console (this happens by default).
-c CONFIG, --config CONFIG	This is the location of the configuration file for the connector. This location must be readable and writable by the current user. If no config file path is given, the current directory will be used. This file is also where some information from each run of the connector may be put (last run time, private oauth, etc.)
-v {1,2,3}, --verbosity {1,2,3}	This is the logging verbosity level where 3 means everything.
-n, --name	Optional - Name of the connector (Option used in order to allow users to configure multiple connector instances on the same TQ box).
-o, --org-only	Only get samples from your Organization.
-ds, --disable-ssl	Disable SSL verifications when contacting the AutoFocus API server.

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 * * * tqAutoFocus -c stdout -ll /var/log/tq_labs/ -v3  
4. Save and exit CRON.

Known Issues / Limitations

• Depending on the number of updated/new samples to download, the upload can take quite some time. (>1 hour).

Change Log

• Version 2.0.1
  • Resolved a stack error with the connector.  
• Version 2.0.0
  • Refactored code and brought it up to current standards.
  • Improved logging by providing more details.
  • Added support for event tags (using UI tag list).
  • Added support for region attributes for sample events.
  • Added support for custom connector name to give the ability to run multiple instances of the integration.
  • Added support for a custom filetype for the sample search.
• Version 1.0.0
  • Initial release