Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

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.

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

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.

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.