About the connector
ThreatQuotient (ThreatQ) delivers an open and extensible threat intelligence platform (TIP) to provide defenders the context, customization, and collaboration required to increase security effectiveness and efficiently handle threat operations and management.
This document provides information about the ThreatQ connector, which facilitates automated interactions, with a ThreatQ server using FortiSOAR™ playbooks. Add the ThreatQ connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching and retrieving details about a specific indicator, retrieving a list of indicator types, their statuses, and IDs.
Version information
Connector Version: 1.0.1
Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later.
Compatibility with ThreatQ Versions: 3.1.3-167 and later
Release Notes for version 1.0.1
Following enhancements have been made to the ThreatQ Connector in version 1.0.1:
- Added annotations to functions.
- Changed the following operation names: Get Event updated to Search Event and Get Indicator updated to Search Indicator.
- Added parameters to the Get List of Indicators operation.
- Updated parameters for the following operations: Create Adversary, Create IOC, Get List of Indicators, and Get List of Events.
- Added the following operations and playbooks: Get IP Reputation, Get Domain Reputation, Get URL Reputation, and Get File Reputation.
Installing the connector
For the procedure to install a connector, click here.
Prerequisites to configuring the connector
- You must have the URL and credentials of the ThreatQ server on which you will perform the automated operations.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, select the ThreatQ connector and click Configure to configure the following parameters:
| Parameter |
Description |
| Hostname |
IP or Hostname of the ThreatQ server from where the connector gets notifications. |
| Username |
Username to access the ThreatQ server to which you will connect and perform automated operations. |
| Password |
Password to access the ThreatQ server to which you will connect and perform automated operations. |
| Client_Id |
User-provided Client ID. You can find the client id on the OAuth Management page. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Create Event |
Creates a new event in ThreatQ based on the event type and event source that you specify. |
create_event
Investigation |
| Create Adversary |
Creates a new adversary in ThreatQ based on the adversary name and source that you specify. |
create_adversary
Investigation |
| Create IOC |
Creates a new IOC in ThreatQ based on the indicator name, source, type, and status that you specify. |
create_ioc
Investigation |
| Get Indicator Types |
Retrieves a list containing all available indicator types from ThreatQ. |
get_indicator_types
Investigation |
| Get Indicator Statuses |
Retrieves a list containing all available indicator statuses and their id values from ThreatQ.
You can use these IDs to create new indicators. |
get_indicator_status
Investigation |
| Get Reputation |
Retrieves the reputation for the indicator from ThreatQ, based on the indicator name and type that you specify. |
get_reputation
Investigation |
| Search Indicator |
Queries ThreatQ for an indicator that you specify using the name of the indicator and this operation retrieves details for the specified indicator. |
search_indicator
Investigation |
| Get IP Reputation |
Retrieves the reputation for an IP from ThreatQ, based on the IP address that you specify. |
get_ip_reputation
Investigation |
| Get Domain Reputation |
Retrieves the reputation for a domain from ThreatQ, based on the domain name that you specify. |
get_domain_reputation
Investigation |
| Get URL Reputation |
Retrieves the reputation for a URL from ThreatQ, based on the URL type (either URL or URL path) and URL value that you specify. |
get_url_reputation
Investigation |
| Get File Reputation |
Retrieves the reputation for a file from ThreatQ, based on the filehash type and filehash value that you specify. |
get_file_reputation
Investigation |
| Get List of Indicators |
Retrieves a list of available indicators from ThreatQ, based on the parameters that you have specified. |
get_iocs
Investigation |
| Get Related IOCs |
Retrieves details for IOCs related to an indicator from ThreatQ, based on the name of the indicator that you specify. |
get_iocs
Investigation |
| Get Event Types |
Retrieves a list containing all available event types from ThreatQ. |
get_event_types
Investigation |
| Search Event |
Queries ThreatQ for an event that you specify using the name of the indicator and this operation retrieves details for the specified event. |
search_event
Investigation |
| Get List of Events |
Retrieves a list containing all the evens from ThreatQ. |
get_event
Investigation |
| Update Indicator Status |
Updates the status of the indicator, in ThreatQ, based on the name of the indicator that you specify. |
update_ioc
Investigation |
| Link IOCs |
Links two IOCs in ThreatQ, based on the names of the indicators that you specify. |
link_ioc
Investigation |
operation: Create Event
Input parameters
| Parameter |
Description |
| Event Type |
Type of the event that you want to create in ThreatQ.
Event types are defined in ThreatQ and you can choose from the following: Spearphish, Watering Hole, SQL Injection Attack, DoS Attack, Malware, Watchlist, Command and Control, Anonymization Exfiltration, Host Characteristics, Compromised PKI Certificate, Login Compromise, and Incident.
You can fetch the event types using the Get Event Types operation. |
| Title |
Name to be given to the newly created event in ThreatQ. |
| Source |
Name of the source from where you are creating this event. |
| Description |
(Optional) Description to be added to the newly created event in ThreatQ. |
Output
The JSON output retrieves the details of the newly created event from ThreatQ.
Following image displays a sample output:
operation: Create Adversary
Input parameters
| Parameter |
Description |
| Adversary Name |
Name to be given to the newly created adversary in ThreatQ. |
| Source |
Name of the source from where you are creating this adversary. |
| Description |
(Optional) Description to be added to the newly created adversary in ThreatQ. |
Output
The JSON output retrieves the details of the newly created adversary from ThreatQ.
Following image displays a sample output:
operation: Create IOC
Input parameters
| Parameter |
Description |
| Indicator Value |
Name of the indicator to be created in ThreatQ. |
| Indicator Type |
Type of the indicator that you want to create in ThreatQ.
Indicator types are defined in ThreatQ and you can choose from the following: Email Address, Email Attachment, Email Subject, X-Mailer, FQDN, IP Address, Mutex, Username, Password, File Path, Filename, MD5, SHA-1, SHA-256, SHA-384, SHA-512, String, Fuzzy Hash, GOST Hash, URL, URL Path, User-agent, Registry Key, CVE, and CIDR Block.
You can fetch the indicator types using the Get Indicator Types operation. |
| Indicator Status |
Status of the indicator that you want to create in ThreatQ.
Indicator statuses are defined in ThreatQ and you can choose from the following: Active, Expired, Indirect, Review, White Listed, and Black Listed.
You can fetch the indicator statuses using the Get Indicator Statuses operation. |
| Source |
Name of the source from where you are creating this IOC. |
Output
The JSON output retrieves the details of the newly created indicator from ThreatQ.
Following image displays a sample output:
operation: Get Indicator Types
Input parameters
You do not need to provide any input parameters for this operation. Include this operation in the ThreatQ playbook and you will get a list containing all available indicator types.
Output
The JSON retrieves a list of all available indicator types from ThreatQ.
Following image displays a sample output:
operation: Get Indicator Statuses
Input parameters
You do not need to provide any input parameters for this operation. Include this operation in the ThreatQ playbook and you will get a list containing all available indicator statuses and their id values. You can use these IDs to create new indicators.
Output
The JSON retrieves a list of all available indicator statuses and their id values from ThreatQ.
Following image displays a sample output:
operation: Get Reputation
Input parameters
| Parameter |
Description |
| Indicator Type |
Type of the indicator for which you want to retrieve reputation from ThreatQ.
Indicator types are defined in ThreatQ and you can choose from the following: Email Address, Email Attachment, Email Subject, X-Mailer, FQDN, IP Address, Mutex, Username, Password, File Path, Filename, MD5, SHA-1, SHA-256, SHA-384, SHA-512, String, Fuzzy Hash, GOST Hash, URL, URL Path, User-agent, Registry Key, CVE, and CIDR Block.
You can fetch the indicator types using the Get Indicator Types operation. |
| Indicator |
Name of the indicator for which you want to retrieve reputation from ThreatQ. |
Output
The JSON output retrieves the reputation for the indicator from ThreatQ, based on the indicator name and type that you have specified.
Following image displays a sample output:
operation: Search Indicator
Input parameters
| Parameter |
Description |
| Indicator |
Name of the indicator that which you want to search for in ThreatQ and whose details you want to retrieve from ThreatQ. |
Output
The JSON output retrieves the details for the indicator from ThreatQ, based on the indicator name that you have specified.
Following image displays a sample output:
operation: Get IP Reputation
Input parameters
| Parameter |
Description |
| IP Address |
IP address for which you want to retrieve reputation from ThreatQ. |
Output
The JSON output retrieves the reputation for the IP from ThreatQ, based on the IP address you have specified.
Following image displays a sample output:
operation: Get Domain Reputation
Input parameters
| Parameter |
Description |
| Domain |
Name of the domain for which you want to retrieve reputation from ThreatQ. |
Output
The JSON output retrieves the reputation for the domain from ThreatQ, based on the domain name you have specified.
Following image displays a sample output:
operation: Get URL Reputation
Input parameters
| Parameter |
Description |
| Indicator Type |
Type of indicator (URL in this case) for which you want to retrieve reputation from ThreatQ.
Indicator types are defined in ThreatQ and you can choose from the following: URL or URL Path.
You can fetch the indicator types using the Get Indicator Types operation. |
| Indicator Value |
Value of the URL for which you want to retrieve reputation from ThreatQ. |
Output
The JSON output retrieves the reputation for the URL from ThreatQ, based on the URL type and value you have specified.
Following image displays a sample output:
operation: Get File Reputation
Input parameters
| Parameter |
Description |
| Indicator Type |
Type of indicator (File in this case) for which you want to retrieve reputation from ThreatQ.
Indicator types are defined in ThreatQ and you can choose from the following: File Path, Filename, MD5, SHA-1, SHA-256, SHA-384, or SHA-512.
You can fetch the indicator types using the Get Indicator Types operation. |
| Indicator Value |
Value of the file for which you want to retrieve reputation from ThreatQ. |
Output
The JSON output retrieves the reputation for the file from ThreatQ, based on the file type and value you have specified.
Following image displays a sample output:
operation: Get List of Indicators
Input parameters
| Parameter |
Description |
| Record Count |
(Optional) Maximum number of indicators that the operation should return.
By default, this is set to 100. |
| Sort By |
(Optional) Indicators are sorted by either the indicator create date or the indicator update date. Therefore, you can choose between Create or Update.
By default, this is set to Create. |
| Indicator Class |
(Optional) Class of indicator for which you want to retrieve the list of indicators.
Indicator classes are defined in ThreatQ and you can choose from the following: Network or Host. |
Output
The JSON retrieves a list of available indicators from ThreatQ, based on the parameters that you have specified.
Following image displays a sample output, where the record count is set to 110, records are sorted by Create, and the indicator class is set to Network:
operation: Get Related IOCs
Input parameters
| Parameter |
Description |
| Indicator |
Name of the indicator for which you want to fetch the related IOCs. |
Output
The JSON output retrieves the details for the related indicator(s) from ThreatQ, based on the indicator name you have specified.
Following image displays a sample output:
operation: Get Event Types
Input parameters
You do not need to provide any input parameters for this operation. Include this operation in the ThreatQ playbook and you will get a list containing all available event types and their ID values.
Output
The JSON retrieves a list of all available event types from ThreatQ.
Following image displays a sample output:
operation: Search Event
Input parameters
| Parameter |
Description |
| Event Name |
Name of the event that which you want to search for in ThreatQ and whose details you want to retrieve from ThreatQ. |
Output
The JSON output retrieves the details for the specified event from ThreatQ, based on the event name you have specified. If the event that you have specified is not found, an error message is displayed.
Following image displays a sample output:
operation: Get List of Events
Input parameters
| Parameter |
Description |
| Offset |
(Optional) Index of the first item to return. By default, this is set to 0. |
| Record Count |
(Optional) Maximum number of events that the operation should return.
By default, this is set to 10. |
| Event Type |
(Optional) Type of event for which you want to retrieve the list of events from ThreatQ.
Event types are defined in ThreatQ and you can choose from the following: Spearphish, Watering Hole, SQL Injection Attack, DoS Attack, Malware, Watchlist, Command and Control, Anonymization Exfiltration, Host Characteristics, Compromised PKI Certificate, Login Compromise, and Incident.
You can fetch the event types using the Get Event Types operation. |
| Event Sources |
(Optional) Name of the event sources for which you want to retrieve the list of events from ThreatQ. |
Output
The JSON retrieves a list of all available events from ThreatQ that match the parameters that you have specified.
Following image displays a sample output:
operation: Update Indicator Status
Input parameters
| Parameter |
Description |
| Indicator |
Name of the indicator whose status you want to update. |
| Indicator Status |
Status of the indicator that you want to update in ThreatQ.
Indicator statuses are defined in ThreatQ and you can choose from the following: Active, Expired, Indirect, Review, White Listed, and Black Listed.
You can fetch the indicator statuses using the Get Indicator Statuses operation. |
| Indicator Class |
(Optional) Class of indicator that contains the indicator you want to update.
Indicator classes are defined in ThreatQ and you can choose from the following: Network or Host. |
Output
The JSON output retrieves the details for the indicator from ThreatQ whose status you want to update.
Following image displays a sample output:
operation: Link IOCs
Input parameters
| Parameter |
Description |
| Indicator |
Name of the indicator that you want to relate to another indicator. |
| Link Indicator |
Name of the indicator which you want to relate to the first indicator. |
Output
The JSON output retrieves the details for the indicator (first) from ThreatQ to which you want to create a link containing the second indicator.
Following image displays a sample output:
Included playbooks
The Sample - ThreatQ - 1.0.1 playbook collection comes bundled with the ThreatQ connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ThreatQ connector.
- Create Adversary
- Create Event
- Create IOC
- Get Domain Reputation
- Get Event Types
- Get File Reputation
- Get Indicator Statuses
- Get Indicator Types
- Get IP Reputation
- Get List of Events
- Get List of Indicators
- Get Related IOCs
- Get Reputation
- Get URL Reputation
- Link IOCs
- Search Event
- Search Indicator
- Update Indicator Status
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.
