ThreatConnect v2.0.0

About the connector

ThreatConnect combines external threat data from trusted sources with your in-house data to eliminate false positives and discover relevant threats. It leverages automation to gain context and enhance your data with enrichment tools quickly. It also uses visualization to hunt for patterns and trends to uncover threat actor capabilities and techniques.

This document provides information about the ThreatConnect connector, which facilitates automated interactions with the ThreatConnect API using FortiSOAR™ playbooks. Add the ThreatConnect connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving the reputation of specified IP addresses, files, or email addresses.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 7.2.2-1098

ThreatConnect Version Tested on: 6.2.2

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.0.0

The following enhancements have been made to the ThreatConnect connector in version 2.0.0:

• Updated the connector to version 3 of the ThreatConnect REST API, and therefore updated all the actions to use this version of the API.
• Renamed the following actions and added a new input parameter named "Include Additional Params":
  • Hunt Email renamed to Get Email Reputation
  • Hunt File Hash renamed to Get File Reputation
  • Hunt Host renamed to Get Host Reputation
  • Hunt IP renamed to Get IP Reputation
  • Hunt URL renamed to Get URL Reputation
• Added the following operations and playbooks:
  • List Indicator
  • Invoke ThreatConnect REST API

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-threatconnect

Prerequisites to configuring the connector

• You must have the URL of the ThreatConnect server to which you will connect and perform the automated operations.
• You must know the default organization that is configured for your account to access the ThreatConnect API and the access ID and secret key used to access the ThreatConnect API.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the ThreatConnect server.

Minimum Permissions Required

• Not Applicable.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the ThreatConnect connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter	Description
Server URL	The URL of the ThreatConnect server to which you will connect and perform the automated operations.
Access ID	The access ID that is configured for your account to access the ThreatConnect API to which you will connect and perform the automated operations.
Secret Key	The secret Key that is configured for your account to access the ThreatConnect API to which you will connect and perform the automated operations.
Default Organization	The default organization that is configured for your account to access the ThreatConnect API to which you will connect and perform the automated operations.
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:

Function	Description	Annotation and Category
Get IP Reputation	Retrieves the reputation for a specific IP address using the ThreatConnect API based on the IP address and other input parameters you have specified.	ip_reputation Investigation
Get File Reputation	Retrieves the reputation of a specific file hash using the ThreatConnect API based on the file hash and other input parameters you have specified.	file_reputation Investigation
Get Email Reputation	Retrieves the reputation for a specific email address using the ThreatConnect API based on the email address and other input parameters you have specified.	email_reputation Investigation
Get URL Reputation	Retrieves the reputation of a specific URL using the ThreatConnect API based on the URL address and other input parameters you have specified.	url_reputation Investigation
Get Host Reputation	Retrieves the reputation of a specific host using the ThreatConnect API based on the hostname and other input parameters you have specified.	host_reputation Investigation
List Indicator	Retrieves indicators using the ThreatConnect API based on the input parameters you have specified.	list_indicator Investigation
Invoke ThreatConnect REST API	Invokes a function to 'Get an API' endpoint on the ThreatConnect server based on the endpoint you have specified.	api_call

operation: Get IP Reputation

Input parameters

Parameter	Description
IP Address	Specify the IP address whose reputation information you want to retrieve using the ThreatConnect API.
Owner	(Optional) The owner of the IP address whose reputation you want to retrieve using the ThreatConnect API. The owner that you specify in this field overwrites the owner that you have specified in the 'Default Organization' configuration parameter. For example, Fortinet
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation. If you select this option, then from the Include Fields list, select one or more parameters whose keys you want to include in the response of this operation. You can choose any or all of the following options: Tags, Threat Assess, and/or Associated Groups. If you choose Associated Groups, then select the Attributes option to include the 'associatedGroups.attributes' keys in the response of this operation.

Output

The output contains the following populated JSON schema:

Output schema when you choose "Include Additional Params" as "true":
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"ip": "",
"rating": "",
"confidence": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
},
"status": ""
}

This is the default output schema:
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"ip": "",
"rating": "",
"confidence": ""
},
"status": ""
}

operation: Get File Reputation

Input parameters

Parameter	Description
File Hash	Specify the file hash whose reputation information you want to retrieve using the ThreatConnect API.
Owner	(Optional) The owner of the file hash whose reputation you want to retrieve using the ThreatConnect API. The owner that you specify in this field overwrites the owner that you have specified in the 'Default Organization' configuration parameter. For example, Fortinet
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation. If you select this option, then from the Include Fields list, select one or more parameters whose keys you want to include in the response of this operation. You can choose any or all of the following options: Tags, Threat Assess, and/or Associated Groups. If you choose Associated Groups, then select the Attributes option to include the 'associatedGroups.attributes' keys in the response of this operation.

Output

The output contains the following populated JSON schema:

Output schema when you choose "Include Additional Params" as "true":
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"md5": "",
"confidence": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
},
"status": ""
}

This is the default output schema:
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"md5": "",
"confidence": ""
},
"status": ""
}

operation: Get Email Reputation

Input parameters

Parameter	Description
Email Address	Specify the email address whose reputation information you want to retrieve using the ThreatConnect API.
Owner	(Optional) The owner of the email address whose reputation you want to retrieve using the ThreatConnect API. The owner that you specify in this field overwrites the owner that you have specified in the 'Default Organization' configuration parameter. For example, Fortinet
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation. If you select this option, then from the Include Fields list, select one or more parameters whose keys you want to include in the response of this operation. You can choose any or all of the following options: Tags, Threat Assess, and/or Associated Groups. If you choose Associated Groups, then select the Attributes option to include the 'associatedGroups.attributes' keys in the response of this operation.

Output

The output contains the following populated JSON schema:

Output schema when you choose "Include Additional Params" as "true":
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"address": "",
"rating": "",
"confidence": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
},
"status": ""
}

This is the default output schema:
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"rating": "",
"address": "",
"confidence": ""
},
"status": ""
}

operation: Get URL Reputation

Input parameters

Parameter	Description
URL	Specify the URL whose reputation information you want to retrieve using the ThreatConnect API.
Owner	(Optional) The owner of the URL whose reputation you want to retrieve using the ThreatConnect API. The owner that you specify in this field overwrites the owner that you have specified in the 'Default Organization' configuration parameter. For example, Fortinet
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation. If you select this option, then from the Include Fields list, select one or more parameters whose keys you want to include in the response of this operation. You can choose any or all of the following options: Tags, Threat Assess, and/or Associated Groups. If you choose Associated Groups, then select the Attributes option to include the 'associatedGroups.attributes' keys in the response of this operation.

Output

Output schema when you choose "Include Additional Params" as "true":
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"text": "",
"rating": "",
"confidence": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
},
"status": ""
}

This is the default output schema:
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"text": "",
"rating": "",
"confidence": ""
},
"status": ""
}

operation: Get Host Reputation

Input parameters

Parameter	Description
Hosts	Specify the host whose reputation information you want to retrieve using the ThreatConnect API.
Owner	(Optional) The owner of the host whose reputation you want to retrieve using the ThreatConnect API. The owner that you specify in this field overwrites the owner that you have specified in the 'Default Organization' configuration parameter. For example, Fortinet
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation. If you select this option, then from the Include Fields list, select one or more parameters whose keys you want to include in the response of this operation. You can choose any or all of the following options: Tags, Threat Assess, and/or Associated Groups. If you choose Associated Groups, then select the Attributes option to include the 'associatedGroups.attributes' keys in the response of this operation.

Output

The output contains the following populated JSON schema:

Output schema when you choose "Include Additional Params" as "true":
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"rating": "",
"hostName": "",
"dnsActive": "",
"confidence": "",
"whoisActive": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
},
"status": ""
}

This is the default output schema:
{
"data": {
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"rating": "",
"hostName": "",
"dnsActive": "",
"confidence": "",
"whoisActive": ""
},
"status": ""
}

operation: List Indicator

Input parameters

Parameter	Description
Include Additional Params	(Optional) Select this option to include the 'tags', 'threatAssess', and 'associatedGroups.attributes' keys in the response of this operation.
Limit	(Optional) The number of records that should be returned in a single search. By default, it is set as "100", and the maximum value that can be specified for 'resultLimit' is 10000.
Offset	(Optional) The offset value retrieves a subset of records that starts from the offset value. The offset works with the 'Limit' parameter to determine how many records to retrieve starting from the offset. By default, it is set as "0".

Output

The output contains the following populated JSON schema:

Output schema when you choose "Include Additional Params" as "true":
{
"data": [
{
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"ip": "",
"tags": {
"data": [
{
"id": "",
"name": "",
"lastUsed": ""
}
]
},
"rating": "",
"confidence": "",
"associatedGroups": {},
"threatAssessScore": "",
"threatAssessRating": "",
"threatAssessConfidence": ""
}
],
"status": ""
}

This is the default output schema:
{
"data": [
{
"id": "",
"ownerName": "",
"dateAdded": "",
"webLink": "",
"type": "",
"lastModified": "",
"summary": "",
"privateFlag": "",
"active": "",
"activeLocked": "",
"confidence": "",
"md5": ""
}
],
"status": ""
}

operation: Invoke ThreatConnect REST API

Input parameters

Parameter	Description
Endpoint	The endpoint for which you want to invoke the function on the ThreatConnect server. For example, /api/v3/tags For information on the available endpoints in v3 of the ThreatConnect API, see the Available Endpoints section of the ThreatConnect API documentation.

Output

The output contains a non-dictionary value.

Included playbooks

The Sample - ThreatConnect - 2.0.0 playbook collection comes bundled with the ThreatConnect 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 ThreatConnect connector.

• Get Email Reputation
• Get File Reputation
• Get Host Reputation
• Get IP Reputation
• Get URL Reputation
• Invoke ThreatConnect REST API
• List Indicator

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 the connector upgrade and delete.