About the connector
ThreatSTOP is a cloud-based automated threat intelligence platform that converts the latest threat data into enforcement policies, and automatically updates your firewalls, routers, DNS servers and endpoints to stop attacks before they become breaches.
This document provides information about the ThreatSTOP connector, which facilitates automated interactions, with a ThreatSTOP server using FortiSOAR™ playbooks. Add the ThreatSTOP connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating an IOC in ThreatSTOP, returning a list of DNS Firewall policies from ThreatSTOP, and adding an IP to the specific IP UDL in ThreatSTOP.
Version information
Connector Version: 1.0.0
FortiSOAR™ Version Tested on: 4.12.1-253
Authored By: Fortinet
Certified: Yes
Installing the connector
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-threatstop
For the detailed procedure to install a connector, click here
Prerequisites to configuring the connector
- You must have the URL of ThreatSTOP server to which you will connect and perform automated operations.
- You must have the API key to access the ThreatSTOP REST API.
- 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, click the ThreatSTOP connector row, and in the Configuration tab enter the required configuration details.
| Parameter |
Description |
| Server URL |
IP address or Hostname of the ThreatSTOP server to which you will connect and perform automated operations. |
| API Key |
API key that is provided to you by a ThreatSTOP administrator that you will use to access the ThreatSTOP REST API. |
| 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 and onwards:
| Function |
Description |
Annotation and Category |
| Check IOC |
Returns research information from ThreatSTOP based on the Indicator of Compromise (IOC) value that you have specified |
check_ioc
Investigation |
| Create IOC |
Creates an IOC in ThreatSTOP based on the IP address or domain and other input parameters you have specified. This operation will also return data for the specified IOCs. |
create_ioc
Investigation |
| Get Devices Details |
Get details of all devices or details of a specific user device, based on the user device ID you have specified, from ThreatSTOP. |
get_devices
Investigation |
| Get Log Details |
Returns statistics for all log files, including date uploaded and number of blocks or a specific log files, based on the object ID you have specified, from ThreatSTOP. |
get_log_details
Investigation |
| Get IP Policies |
Returns a list of all IP Firewall policies or a specific IP Firewall policy, based on the policy object ID you have specified, from ThreatSTOP. |
get_ip_policies
Investigation |
| Get Domain Policies |
Returns a list of all DNS Firewall policies or a specific DNS Firewall policy, based on the policy object ID you have specified, from ThreatSTOP. |
get_domain_policies
Investigation |
| Get IP UDLs |
Returns a list of IP User Defined Lists (UDLs)
Returns a list of all IP User Defined Lists (UDLs) or a specific IP UDL policy, based on the user list object ID you have specified, from ThreatSTOP. |
get_ip_udls
Investigation |
| Create IP UDL |
Creates a new IP UDL in ThreatSTOP based on list Name, list Type, IP address, a other input parameters you have specified. |
create_ip_udl
Investigation |
| Add IP to IP UDL |
Adds an IP to the specific IP UDL in ThreatSTOP based on user list object ID, list type, IP address, and other input parameters you have specified. |
add_ip_to_ip_udl
Investigation |
| Delete IP from IP UDL |
Removes a specific IP from a IP UDL in ThreatSTOP based on the user list object ID you have specified. |
delete_ip_from_ip_udl
Investigation |
| Get Domain UDLs |
Returns a list of all Domain UDLs or a specific Domain UDL, based on the user list object ID you have specified, from ThreatSTOP. |
get_domain_udls
Investigation |
| Create Domain UDL |
Creates a new IP UDL in ThreatSTOP based on list name, list type, domain name, a other input parameters you have specified. |
create_domain_udl
Investigation |
| Add Domain to Domain UDL |
Adds a domain to the specific domain UDL in ThreatSTOP based on user list object ID, list type, domain name, and other input parameters you have specified. |
add_domain_to_domain_udl
Investigation |
| Delete Domain from Domain UDL |
Removes a specific domain from a domain UDL in ThreatSTOP based on the user list object ID you have specified. |
delete_domain_from_domain_udl
Investigation |
operation: Check IOC
Input parameters
| Parameter |
Description |
| IOC Value |
Value of the IOC whose research information you want to retrieve from ThreatSTOP.
An IOC value can consist of an IP address, a domain that has at least one subdomain and a leading wild card. For example, *.google.com |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": "",
"disclaimer": ""
},
"_data": [
{
"ioc": "",
"info": {
"asn_info": {},
"active": [],
"asn_data": [],
"history": [
{
"ioc": "",
"last_used": "",
"blocker": {
"danger_level": "",
"last_update": "",
"description": "",
"public_description": "",
"short_description": "",
"name": ""
},
"first_identified": "",
"address": ""
}
]
}
}
]
}
operation: Create IOC
Input parameters
| Parameter |
Description |
| Domain or IP Address |
Domain name of IP address based on which you want to create an IOC in ThreatSTOP. |
| Strategy |
Choose between Include or Exclude. If you choose Include then the targets that you specify will be included.
Note: This parameter requires you to provide targets. If targets are not provided then it parameter does not work. |
| Targets |
(Optional) Comma-separated list of targets to either include or exclude.
For example, BOTSBLK, TS-RANS, MSISACEX |
| Last Seen |
(Optional) Number of seconds to look back in ThreatSTOP from the current time. For example, 1 month would be 2592000 seconds. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": "",
"disclaimer": ""
},
"_data": [
{
"ioc": "",
"info": {
"related_records": [],
"active": [
{
"ioc": "",
"first_identified": "",
"blocker": {
"danger_level": "",
"last_update": "",
"description": "",
"name": "",
"short_description": "",
"public_description": ""
},
"last_used": "",
"domain": ""
}
],
"history": []
}
}
]
}
operation: Get Devices Details
Input parameters
| Parameter |
Description |
| User Device ID |
(Optional) ID of the user device whose details you want to retrieve from ThreatSTOP. If you specify the user device ID, then this operation will return a list containing a single device object.
If you do not specify any user device ID, then this operation will return a list containing the details of all devices, limited to the number of devices to which the user has access, based on the users authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 user devices. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_data": [
{
"policy": {
"_links": {
"policy": {
"href": ""
}
},
"object_id": "",
"name": ""
},
"tdid": "",
"serial_number": "",
"object_id": "",
"device_class": "",
"device_model": "",
"device_nickname": "",
"service_type": "",
"ip_address": "",
"_links": {
"self": {
"href": ""
}
},
"device_manufacturer": ""
}
]
}
operation: Get Log Details
Input parameters
| Parameter |
Description |
| Object ID |
(Optional) Object ID of the log whose details you want to retrieve from ThreatSTOP. If you specify the object ID, then this operation will return a list containing a single log object.
If you do not specify any object ID, then this operation will return a list containing the details of all logs, limited to the number of log objects to which the user has access, based on the user's authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 log objects. |
| Limit |
(Optional) If you specify the object ID then this parameter is ignored. If you do not specify any object ID, then this operation will return a list containing the details of all logs, limited to the number specified in this operation. By default this is set to 10. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"previous": {
"href": ""
},
"next": {
"href": ""
},
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"date_received": "",
"_links": {
"self": {
"href": ""
}
},
"object_id": "",
"device": {
"_links": {
"self": {
"href": ""
}
},
"object_id": ""
},
"skipped": "",
"date_processed": "",
"date_first_entry": "",
"errors": "",
"matches": "",
"blocked_out": "",
"status": "",
"blocked_in": "",
"allowed_out": "",
"allowed_in": "",
"date_last_entry": ""
}
]
}
operation: Get IP Policies
Input parameters
| Parameter |
Description |
| Policy Object ID |
(Optional) Policy object ID whose IP Firewall policy details you want to retrieve from ThreatSTOP. If you specify the policy object ID, then this operation will return a list containing a single IP policy object.
If you do not specify any policy object ID, then this operation will return a list containing the details of all IP firewall policies, limited to the number of IP policy objects to which the user has access, based on the user's authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 IP policy objects. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"global": "",
"object_id": "",
"visible": 1,
"threatlist_ioc_format": "",
"owned_by_user": "",
"threatlist_ioc_type": "",
"trial": "",
"policy_type": "",
"_links": {
"self": {
"href": ""
}
},
"all_policy_targets": [
{
"_links": {
"target": {
"href": ""
}
},
"danger_level": "",
"object_id": "",
"last_update": "",
"behavior": "",
"description": "",
"is_ip": "",
"handle_name": "",
"short_description": ""
}
],
"targets": [
{
"_links": {
"target": {
"href": ""
}
},
"danger_level": "",
"object_id": "",
"last_update": "",
"behavior": "",
"description": "",
"is_ip": "",
"handle_name": "",
"short_description": ""
}
],
"expert_mode": "",
"user_lists": [],
"excluded_targets": [],
"threatlist_enabled": "",
"allow_dns_name": "",
"policy_name": "",
"description": "",
"public": "",
"target_bundles": [],
"domain": "",
"dns_name": ""
}
]
}
operation: Get Domain Policies
Input parameters
| Parameter |
Description |
| Policy Object ID |
(Optional) Policy object ID whose domain policy details you want to retrieve from ThreatSTOP. If you specify the policy object ID, then this operation will return a list containing a single domain policy object.
If you do not specify any policy object ID, then this operation will return a list containing the details of all domain policies, limited to the number of domain policy objects to which the user has access, based on the user's authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 domain policy objects. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"default_action": "",
"global": true,
"object_id": "",
"visible": 1,
"threatlist_ioc_format": "",
"owned_by_user": "",
"policy_type": "",
"threatlist_ioc_type": "",
"trial": "",
"excluded_targets": [],
"_links": {
"self": {
"href": ""
}
},
"all_policy_targets": [
{
"_links": {
"target": {
"href": ""
}
},
"danger_level": "",
"object_id": "",
"last_update": "",
"behavior": "",
"description": "",
"is_ip": "",
"handle_name": "",
"short_description": ""
}
],
"targets": [
{
"_links": {
"target": {
"href": ""
}
},
"danger_level": "",
"object_id": "",
"last_update": "",
"behavior": "",
"description": "",
"is_ip": "",
"handle_name": "",
"short_description": ""
}
],
"expert_mode": "",
"user_lists": [],
"threatlist_enabled": "",
"allow_dns_name": "",
"policy_name": "",
"description": "",
"public": "",
"target_bundles": [],
"domain": "",
"dns_name": ""
}
]
}
operation: Get IP UDLs
Input parameters
| Parameter |
Description |
| User List Object ID |
Optional) User List object ID whose IP UDL details you want to retrieve from ThreatSTOP. If you specify the user list object ID, then this operation will return a list containing a single user list object.
If you do not specify any user list object ID, then this operation will return a list containing the details of all IP UDLs, limited to the number of user list objects to which the user has access, based on the user's authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 user list objects. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_meta": {
"addresses": {
"total": "",
"count": ""
},
"count": ""
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [],
"object_id": "",
"_meta": {
"addresses": {
"address_count": "",
"record_count": ""
}
},
"description": "",
"allow_bogon": "",
"list_type": "",
"shared": "",
"list_name": ""
}
]
}
operation: Create IP UDL
Input parameters
| Parameter |
Description |
| List Name |
Name of IP User Defined List that you want to create in ThreatSTOP. |
| List Type |
Type of UDL that you want to create in ThreatSTOP. You can choose either Block or Allow.
By default, Block is selected. |
| IP Address |
IP address for UDL that you want to create in ThreatSTOP. |
| Comments |
(Optional) Comments to denote what type of IP address entry you want to make in ThreatSTOP. |
| Description |
(Optional) Description containing the reason why you want to make the IP address entry in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
},
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
}
],
"object_id": "",
"description": "",
"allow_bogon": "",
"list_type": "",
"shared": false,
"list_name": ""
}
]
}
operation: Add IP to IP UDL
Input parameters
| Parameter |
Description |
| User List Object ID |
User List Object ID in which you want to add the specified IP in ThreatSTOP. |
| List Name |
Name of the User IP list in which you want to add the specified IP in ThreatSTOP. |
| List Type |
Type of IP UDL in which you want to add the specified IP. You can choose either Block or Allow.
By default, Block is selected. |
| IP Address |
IP address of the user IP list that you want to add to the IP UDL in ThreatSTOP. |
| Comments |
(Optional) Comments to denote what type of IP address entry you want to make in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_meta": {
"addresses": {
"added_count": "",
"removed_count": "",
"updated_count": ""
}
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
}
],
"object_id": "",
"description": "",
"allow_bogon": "",
"list_type": "",
"shared": "",
"list_name": ""
}
]
}
operation: Delete IP from IP UDL
Input parameters
| Parameter |
Description |
| User List Object ID |
User List Object ID that you want to delete from the IP UDL in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"user_lists": {
"href": ""
}
},
"_data": []
}
operation: Get Domain UDLs
Input parameters
| Parameter |
Description |
| User List Object ID |
(Optional) User list object ID whose domain UDL details you want to retrieve from ThreatSTOP. If you specify the user list object ID, then this operation will return a list containing a single domain user list object.
If you do not specify any user list object ID, then this operation will return a list containing the details of all domain UDLs, limited to the number of domain user list objects to which the user has access, based on the user's authentication token. By default this is set to 10, i.e., this operation will return a list containing details of 10 domain user list objects. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
}
],
"object_id": "",
"description": "",
"shared": "",
"list_name": ""
}
]
}
operation: Create Domain UDL
Input parameters
| Parameter |
Description |
| List Name |
Name of User Domain List that you want to create in ThreatSTOP. |
| List Type[Shared] |
Select True from this drop-down list if you want to create a shared list.
For DNS firewall records this will always be RPZ. |
| Domain Name |
Domain name for UDL that you want to create in ThreatSTOP. |
| Comments |
(Optional) Comments to denote what type of domain address entry you want to make in ThreatSTOP. |
| Description |
(Optional) Description containing the reason why you want to make the domain address entry in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
}
],
"object_id": "",
"description": "",
"shared": false,
"list_name": ""
}
]
}
operation: Add Domain to Domain UDL
Input parameters
| Parameter |
Description |
| User List Object ID |
User List Object ID in which you want to add the specified domain in ThreatSTOP. |
| List Name |
Name of the User domain list in which you want to add the specified domain in ThreatSTOP. |
| List Type[Shared] |
Select True from this drop-down list if you want to create a shared list.
For DNS firewall records this will always be RPZ. |
| Domain Name |
Domain name of the service that you want to add to the domain UDL in ThreatSTOP. |
| Comments |
(Optional) Comments to denote what type of domain address entry you want to make in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"self": {
"href": ""
}
},
"_metadata": {
"request_id": ""
},
"_meta": {
"addresses": {
"added_count": "",
"removed_count": "",
"updated_count": ""
}
},
"_data": [
{
"owner": "",
"_links": {
"self": {
"href": ""
}
},
"addresses": [
{
"comments": "",
"value": "",
"expires": "",
"address_type": ""
}
],
"object_id": "",
"description": "",
"shared": "",
"list_name": ""
}
]
}
operation: Delete Domain from Domain UDL
Input parameters
| Parameter |
Description |
| User List Object ID |
User List Object ID that you want to delete from the Domain UDL in ThreatSTOP. |
Output
The output contains the following populated JSON schema:
{
"_links": {
"user_lists": {
"href": ""
}
},
"_data": []
}
Included playbooks
The Sample - ThreatSTOP - 1.0.0 playbook collection comes bundled with the ThreatSTOP connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in CyOPsTM after importing the ThreatSTOP connector.
- Add Domain to Domain UDL
- Add IP to IP UDL
- Check IOC
- Create Domain UDL
- Create IOC
- Create IP UDL
- Delete Domain from Domain UDL
- Delete IP from IP UDL
- Get Devices Details
- Get Domain Policies
- Get Domain UDLs
- Get IP Policies
- Get IP UDLs
- Get Log Details
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.
