BrightCloud Threat Intelligence Services protect your customers from malicious URLs, IPs, files, and mobile apps by integrating accurate and near real-time threat intelligence into your network and endpoint protection. The platform scans billions of IP addresses and billions of URLs across millions of domains, in addition to millions of mobile apps, and leverages machine learning to classify and categorize each according to the threat it represents to your business.
D3 SOAR is providing REST operations to function with BrightCloud Threat Intelligence.
For example, you can use BrightCloud Threat Intelligence to monitor and dynamically score addresses across the entire IPv4 and in-use IPv6 space, and is able to detect, analyze and classify 60,000 new malicious IP addresses daily.
For each query, BrightCloud Threat Intelligence supports two different protocols: GET and POST. For GET protocol, there is a limit by the length of GET request, for example, the maximum URL length in IE is 2083 characters; It is less secure because data sent is part of the URL. For POST protocol, there is no limit on POST request payload length and more secure because the parameters are not stored in browser history or in web server logs.
Connection
To connect to BrightCloud Threat Intelligence from D3 SOAR, please follow this part to collect the required information below:
Parameter
Description
Example
Server URL
The server URL of BrightCloud Threat Intelligence.
https://api.bcti.brightcloud.com
OEM ID
The OEM ID to authenticate the API connection.
YOUR_OEM_ID
Device ID
The Device ID to authenticate the API connection.
YOUR_DEVICE_ID
Unique ID
The Unique ID to authenticate the API connection.
YOUR_UID
API Version
The API version to use for the connection.
1.0
Configuring D3 SOAR to Work with BrightCloud Threat Intelligence
Log in to D3 SOAR.
Find the BrightCloud Threat Intelligence integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Webroot BCTI in the search box to find the integration, then click it to select it.
Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Webroot BCTI.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System Reputation Check: Checking one or more reputation check tickboxes will run the corresponding check reputation command(s) under this integration connection to enrich the corresponding artifacts with reputation details. For example, we are configuring an integration connection named “ConnectionA” with the site “Sandbox”. All IP artifacts from the “Sandbox” site will go through a reputation check using the Check IP Reputation command from that integration. The return data output from running the command will then be used to update the risk level of the artifacts which may affect the risk level of incoming events.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection. 1. Input the Server URL. The default value is https://api.bcti.brightcloud.com. 2. Input the OEM ID. 3. Input the Device ID. 4. Input the Unique ID. 5. Input the API Version.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active. To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmarkappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click Add to create and add the configured connection.
Commands
Webroot BCTI includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
Check File Reputation
Retrieves the reputation information of the files.
Input
Input Parameter
Required/Optional
Description
Example
File Hashes
Required
The file MD5 or SHA256 hashes.
JSON
[
"*****",
"*****"
]
Output
Return Data
In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.
The table below lists the possible output risk levels with the corresponding return context data:
BCTI Risk Levels
D3 Risk Levels
Risk Level Names
B
1
High
U
4
Default
G
5
Zero Risk
Error Handling
If your command fails to execute, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Check File Reputation failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid hash value sdfads provided, only MD5 or SHA256 hash value is supported.
Error Sample Data
Check File Reputation failed.
Status Code: 401.
Message: Invalid hash value invalidHashDemo provided, only MD5 or SHA256 hash value is supported.
Check IP Reputation
Retrieves reputation information on the specified IP addresses.
Input
Input Parameter
Required/Optional
Description
Example
IPs
Required
The IP addresses used to return reputation information. The IP addresses can be in IPv4, IPv6, or a mix of both formats.
In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.
The table below lists the possible output risk levels with the corresponding return context data:
BCTI Risk Levels
D3 Risk Levels
Risk Level Names
1-20
1
High
21-60
2
Medium
61-80
3
Low
81-100
5
Zero Risk
Error Handling
If your command fails to execute, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Check IP Reputation failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Check IP Reputation failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Check URL Reputation
Retrieves reputation information for the provided URLs.
Input
Input Parameter
Required/Optional
Description
Example
URLs
Required
The URLs used to return reputation information.
JSON
[
"https://xmr.pool.minergate.com"
]
Output
Return Data
In check reputation commands, Return Data converts the risk score from the raw data into D3-defined risk levels as a numerical value (1-5). This will be used to enrich artifacts with reputation information.
The table below lists the possible output risk levels with the corresponding return context data:
BCTI Risk Levels
D3 Risk Levels
Risk Level Names
1-20
1
High
21-60
2
Medium
61-80
3
Low
81-100
5
Zero Risk
Error Handling
If your command fails to execute, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Check URL Reputation failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Check URL Reputation failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get File Info
Returns file information based on its MD5 or SHA256 hash.
Input
Input Parameter
Required/Optional
Description
Example
File Hashes
Required
The file MD5 or SHA256 hashes used to retrieve file information.
JSON
[
"*****",
"*****"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get File Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get File Info failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP File
Returns comprehensive information regarding IP file downloads, including the download links for the full IP files to ensure that the customer's IP files are updated to the latest version.
Input
Input Parameter
Required/Optional
Description
Example
IP File Type
Required
The IP file type to return download links. The available IP file types are:
IP_SPAM_SOURCES
IP_WINDOWS_EXPLOITS
IP_WEB_ATTACKS
IP_BOTNETS
IP_SCANNERS
IP_DOS
IP_REPUTATION
IP_PHISHING
IP_PROXY
IP_MOBILE_THREATS
IP_TOR
All IP Files
IP_SPAM_SOURCES
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP File failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP File failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP Geo File
Returns a download link for the latest version of the geo file. If the provided version is already the latest, no link will be returned.
Input
Input Parameter
Required/Optional
Description
Example
Major Version Number
Required
Your current geo file's major version number. This can be obtained from the geo file name. For instance, in the file name webroot_v1114_20220901_small.csv.zip, the major version is 11, and the minor version is 14.
11
Minor Version Number
Required
Your current geo file's current minor version number. This can be obtained from the geo file name. For instance, in the file name webroot_v1114_20220901_small.csv.zip, the major version is 11, and the minor version is 14.
11
Geo File Type
Required
The geo file type to download. The options are:
Geo file with IP ranges in integer format map to country code
Geo file with IP CIDR maps to geo information
Geo file with IP CIDR maps to geo information (e.g., country code, state, latitude and longitude)
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP Geo File failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP Geo File failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP Geo Info
Retrieves geographic information for the specified IP addresses.
Input
Input Parameter
Required/Optional
Description
Example
IPs
Required
The IP addresses used to return geo information. The IP addresses can be in IPv4, IPv6, or a mix of both formats.
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP Geo Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP Geo Info failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP Reputation History
Retrieves the historical reputation scores associated with the specified IP addresses.
Input
Input Parameter
Required/Optional
Description
Example
IPs
Required
The IP addresses used to return historical reputation scores. A maximum of five IPv4 addresses can be entered per command execution. IPv6 addresses are not supported.
JSON
[
"***.***.***.***",
"***.***.***.***"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP Reputation History failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP Reputation History failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP Threat List
Returns the threat category and bit ID listing.
Input
N/A
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
{
"status": 200,
"type": "ip",
"results": [
{
"ip": "getthreatlist",
"queries": {
"getthreatlist": {
"threats": [
{
"bit": 0,
"category": "Spam Sources",
"desc": "Spam Sources includes Tunneling Spam messages through proxy, anomalous SMTP activities, Forum Spam activities"
},
{
"bit": 1,
"category": "Windows Exploits",
"desc": "Windows exploit category includes active IP Address offering or distributing malware, shell code, rootkits, worms or viruses"
},
{
"bit": 2,
"category": "Web Attacks",
"desc": "Web attacks category includes cross site scripting, iFrame injection, SQL injection, cross domain injection, or domain password brute force attack"
},
{
"bit": 3,
"category": "BotNets",
"desc": "Botnet category includes Botnet C&C channels, and infected zombie machine controlled by Bot master"
}
]
}
}
}
]
}
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
JSON
{
"Bits": [0,1],
"Categories": [ "Spam Sources", "Windows Exploits" ],
"Descriptions": [
"Spam Sources includes Tunneling Spam messages through proxy, anomalous SMTP activities, Forum Spam activities",
"Windows exploit category includes active IP Address offering or distributing malware, shell code, rootkits, worms or viruses"]
}
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
status
200
type
ip
results
{'ip': 'getthreatlist', 'queries': {'getthreatlist': {'threats': [{'bit': 0, 'category': 'Spam Sources', 'desc': 'Spam Sources includes Tunneling Spam messages through proxy, anomalous SMTP activities, Forum Spam activities'}, {'bit': 1, 'category': 'Windows Exploits', 'desc': 'Windows exploit category includes active IP Address offering or distributing malware, shell code, rootkits, worms or viruses'}, {'bit': 2, 'category': 'Web Attacks', 'desc': 'Web attacks category includes cross site scripting, iFrame injection, SQL injection, cross domain injection, or domain password brute force attack'}, {'bit': 3, 'category': 'BotNets', 'desc': 'Botnet category includes Botnet C&C channels, and infected zombie machine controlled by Bot master'}]}}}
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP Threat List failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP Threat List failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get URL Category List
Returns a listing of URL category names along with their corresponding IDs and groups.
Input
N/A
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get URL Category List failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get URL Category List failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get URL Info
Retrieves reputation information for the specified URLs.
Input
Input Parameter
Required/Optional
Description
Example
URLs
Required
The web addresses used to obtain reputation information.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get URL Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get URL Info failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get Full URL WHOIS Info
Retrieves comprehensive WHOIS information for the specified URLs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Full URL WHOIS Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get Full URL WHOIS Info failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get URL File
Returns comprehensive information regarding URL file downloads. The returned download links bring customer URL files to the latest version.
Input
Input Parameter
Required/Optional
Description
Example
URL File Type
Required
The URL file type to return download links. The available URL file types are:
URL_CONTENT
URL_CONTENT_1CAT
URL_CONTENT_1M
URL_REP
URL_REP_1M
URL_REP_1M
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get URL File failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get URL File failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IPv6 Geo File
Returns a download link for the latest version of IPv6 geo file. If the provided version is already up-to-date, no link is returned.
Input
Input Parameter
Required/Optional
Description
Example
Major Version Number
Required
Your current major version number. This can be obtained from the IPv6 geo file name. For example, if the IPv6 geo file file is webroot_IPv6_11_14_20220901.csv.gz, the major version is 11, and the minor version is 14.
11
Minor Version Number
Required
Your current minor version number. This can be obtained from the IPv6 geo file name. For example, if the IPv6 geo file file is webroot_IPv6_11_14_20220901.csv.gz, the major version is 11, and the minor version is 14.
11
IPv6 Geo File Type
Required
The IPv6 geo file type to download. The options are:
Geo file with IPv6 ranges in integer format map to country code
Geo file with IPv6 CIDR maps to geo information
Geo file with IPv6 CIDR maps to geo information
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IPv6 Geo File failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IPv6 Geo File failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get IP Threat History
Returns threat history for the specified IP addresses.
Input
Input Parameter
Required/Optional
Description
Example
IPs
Required
The IP addresses used to return threat history. A maximum of five IPv4 addresses can be entered per command execution.
JSON
[
"***.***.***.***",
"***.***.***.***"
]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get IP Threat History failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get IP Threat History failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Get URL WHOIS Info
Retrieves abbreviated WHOIS information for the specified URLs.
Input
Input Parameter
Required/Optional
Description
Example
URLs
Required
The URLs for which the abbreviated WHOIS information will be retrieved.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get URL WHOIS Info failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Get URL WHOIS Info failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Submit New URI Cats
Submits URLs to the automated crawling system for categorization review. The API response provides an initial notice of receipt of the URLs and a ticket used for logging the request within BrightCloud change request system. There will be no further follow-up notice about the decision regarding the URLs submitted.
READER NOTE
Categories is an optional parameter to run this command.
Run the Get URL Category List command to obtain the Categories. Categories can be found in the raw data at the path $.results[0].queries.getcatlist.cats[*].catid.
Input
Input Parameter
Required/Optional
Description
Example
Email
Optional
The contact email address for receiving potential responses. No automatic notifications will be sent.
A comma-separated list of up to five integers, representing user-suggested category IDs for reclassifying the URLs. Each ID must be between 1 and 83 (inclusive). The category list applies to all submitted URLs. Categories can be obtained using the Get URL Category List command.
[ 2, 3 ]
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Submit New URI Cats failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Error Sample Data
Submit New URI Cats failed.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Error Handling
If the Return Data is failed, an Error tab will appear in the Test Result window.
The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Test Connection failed. Failed to check the connector.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Webroot BCTI portal. Refer to the HTTP Status Code Registry for details.
Status Code: 401.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Unauthorized because of invalid OEM, Device,
or Uid.
Error Sample Data
Test Connection failed. Failed to check the connector.
Status Code: 401.
Message: Unauthorized because of invalid OEM, Device, or Uid.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.