Skip to main content
Skip table of contents

BrightCloud Threat Intelligence

LAST UPDATED: OCT 29, 2024

Overview

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.

Webroot BCTI is available for use in:

D3 SOAR

V12.7+

Category

Data Enrichment

Deployment Options

Option II, Option IV

Known Limitations

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

  1. Log in to D3 SOAR.

  2. Find the BrightCloud Threat Intelligence integration.

    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type Webroot BCTI in the search box to find the integration, then click it to select it.

    4. Click New Connection, on the right side of the Connections section. A new connection window will appear.

  3. Configure the following fields to create a connection to Webroot BCTI.

    1. Connection Name: The desired name for the connection.

    2. 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.

    3. 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.

    4. 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.

    5. Description (Optional): Add your desired description for the connection.

    6. 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.

    7. Configure User Permissions: Defines which users have access to the connection.

    8. Active: Check the tick box to ensure the connection is available for use.

    9. 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.

    10. 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.

    11. 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.

    12. 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.

  4. Test the connection.

    1. 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 checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

    2. Click OK to close the alert window.

    3. 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.

SAMPLE DATA

JSON
[
    {
        "fileHash": "md5",
        "Determination": "B",
        "riskLevel": 1,
        "RawData": {
            "md5": "*****",
            "hash": null,
            "queries": {
                "getinfo": {
                    "md5": "*****",
                    "hash": null,
                    "det": "B",
                    "detdate": 1378958091,
                    "filesize": 234496,
                    "fseen": 1378955978,
                    "malwaregroup": "Pua.Lyrics.Gen",
                    "pccount": 8,
                    "riskLevel": 1
                }
            }
        },
        "BeautifiedHtml": "<table class='cc-table horizontal-table'><tr><th>Type</th><th>Indicator</th><th>Reputation</th><th>Malware Group</th><th>D3 Risk Level</th></tr><tr><td>md5</td><td>*****</td><td>B</td><td>Pua.Lyrics.Gen</td><td>1</td></tr></table>"
    },
    {
        "fileHash": "md5",
        "Determination": "B",
        "riskLevel": 1,
        "RawData": {
            "md5": "*****",
            "hash": null,
            "queries": {
                "getinfo": {
                    "md5": "*****",
                    "hash": null,
                    "det": "B",
                    "detdate": 1381535561,
                    "filesize": 252552,
                    "fseen": 1381534859,
                    "malwaregroup": "Pua.Safemonitor\\searchdonkey",
                    "pccount": 4917,
                    "riskLevel": 1
                }
            }
        },
        "BeautifiedHtml": "<table class='cc-table horizontal-table'><tr><th>Type</th><th>Indicator</th><th>Reputation</th><th>Malware Group</th><th>D3 Risk Level</th></tr><tr><td>md5</td><td>*****</td><td>B</td><td>Pua.Safemonitor\\searchdonkey</td><td>1</td></tr></table>"
    }
]
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "file",
    "results": [
        {
            "md5": "*****",
            "hash": null,
            "queries": {
                "getinfo": {
                    "md5": "*****",
                    "hash": null,
                    "det": "B",
                    "riskLevel": "High",
                    "detdate": 1378958091,
                    "filesize": 234496,
                    "fseen": 1378955978,
                    "malwaregroup": "Pua.Lyrics.Gen",
                    "pccount": 8
                }
            }
        },
        {
            "md5": "*****",
            "hash": null,
            "queries": {
                "getinfo": {
                    "md5": "*****",
                    "hash": null,
                    "det": "B",
                    "riskLevel": "High",
                    "detdate": 1381535561,
                    "filesize": 252552,
                    "fseen": 1381534859,
                    "malwaregroup": "Pua.Safemonitor\\searchdonkey",
                    "pccount": 4917
                }
            }
        }
    ]
}
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
{
  "FileHashes": ["*****","*****"],
  "Determinations": ["B","B"],
  "RiskLevels": ["High","High"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

md5

hash

queries

*****

None

{'getinfo': {'md5': '*****', 'hash': None, 'det': 'B', 'riskLevel': 'High', 'detdate': 1378958091, 'filesize': 234496, 'fseen': 1378955978, 'malwaregroup': 'Pua.Lyrics.Gen', 'pccount': 8}}

*****

None

{'getinfo': {'md5': '*****', 'hash': None, 'det': 'B', 'riskLevel': 'High', 'detdate': 1381535561, 'filesize': 252552, 'fseen': 1381534859, 'malwaregroup': 'Pua.Safemonitor\\searchdonkey', 'pccount': 4917}}

D3-defined Risk Levels

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 error tab 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.

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.

SAMPLE DATA

JSON
[
    {
        "ip": "***.***.***.***",
        "reputation": 9,
        "riskLevel": 1,
        "RawData": {
            "ip": "***.***.***.***",
            "queries": {
                "getinfo": {
                    "ipint": 3627735329,
                    "ip_status": 1,
                    "reputation": 9,
                    "threat_mask": 128,
                    "domain": "***.***.***.***",
                    "domain_age": "24",
                    "threat_count": 19,
                    "current_release_date": 1681868498,
                    "first_release_date": 1441044180,
                    "last_release_date": 1637218806,
                    "riskLevel": 1,
                    "threat_category": "Phishing"
                }
            }
        },
        "BeautifiedHtml": "<table class='cc-table horizontal-table'><tr><th>Type</th><th>Indicator</th><th>Reputation Score</th><th>Category Group</th><th>D3 Risk Level</th></tr><tr><td>IPv4</td><td>***.***.***.***</td><td>9</td><td>Phishing</td><td>1</td></tr></table>"
    },
    {
        "ip": "***:***:***:***:***:***:***:***",
        "reputation": 10,
        "riskLevel": 1,
        "RawData": {
            "ip": "***:***:***:***:***:***:***:***",
            "queries": {
                "getinfo": {
                    "ipint": -1,
                    "ip_status": 1,
                    "reputation": 10,
                    "threat_mask": 130,
                    "threat_count": 10,
                    "current_release_date": 0,
                    "first_release_date": 1601433362,
                    "last_release_date": 1657497601,
                    "riskLevel": 1,
                    "threat_category": "Windows Exploits, Phishing"
                }
            }
        },
        "BeautifiedHtml": "<table class='cc-table horizontal-table'><tr><th>Type</th><th>Indicator</th><th>Reputation Score</th><th>Category Group</th><th>D3 Risk Level</th></tr><tr><td>IPv6</td><td>***:***:***:***:***:***:***:***</td><td>10</td><td>Windows Exploits, Phishing</td><td>1</td></tr></table>"
    }
]
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "ip",
    "results": [
        {
            "ip": "***.***.***.***",
            "queries": {
                "getinfo": {
                    "ipint": 3627735329,
                    "ip_status": 1,
                    "reputation": 7,
                    "riskLevel": 1,
                    "threat_mask": 386,
                    "threat_category": [
                        "Anonymous Proxies",
                        "Phishing",
                        "Windows Exploits"
                    ],
                    "domain": "***.***.***.***",
                    "domain_age": "24",
                    "threat_count": 19,
                    "current_release_date": 1661339358,
                    "first_release_date": 1441044180,
                    "last_release_date": 1637218806
                }
            }
        },
        {
            "ip": "***:***:***:***:***:***:***:***",
            "queries": {
                "getinfo": {
                    "ipint": -1,
                    "ip_status": 1,
                    "reputation": 10,
                    "riskLevel": 1,
                    "threat_mask": 130,
                    "threat_category": [
                        "Phishing",
                        "Windows Exploits"
                    ],
                    "threat_count": 10,
                    "current_release_date": 0,
                    "first_release_date": 1601433362,
                    "last_release_date": 1657497601
                }
            }
        }
    ]
}
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
{
  "IPs": ["***.***.***.***","***:***:***:***:***:***:***:***"],
  "Reputations": [7,10],
  "RiskLevels": ["High","High"],
  "ThreatCategories": [ "Windows Exploits, Phishing, Anonymous Proxies", "Windows Exploits, Phishing" ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ip

queries

***.***.***.***

{'getinfo': {'ipint': 3627735329, 'ip_status': 1, 'reputation': 7, 'riskLevel': 1, 'threat_mask': 386, 'threat_category': ['Anonymous Proxies', 'Phishing', 'Windows Exploits'], 'domain': '***.***.***.***', 'domain_age': '24', 'threat_count': 19, 'current_release_date': 1661339358, 'first_release_date': 1441044180, 'last_release_date': 1637218806}}

***:***:***:***:***:***:***:***

{'getinfo': {'ipint': -1, 'ip_status': 1, 'reputation': 10, 'riskLevel': 1, 'threat_mask': 130, 'threat_category': ['Phishing', 'Windows Exploits'], 'threat_count': 10, 'current_release_date': 0, 'first_release_date': 1601433362, 'last_release_date': 1657497601}}

D3-defined Risk Levels

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 error tab 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.

SAMPLE DATA

JSON
[
    {
        "url": "https://docs.python.org/3/library/hashlib.html",
        "reputation": 100,
        "riskLevel": 5,
        "RawData": {
            "url": "https://docs.python.org/3/library/hashlib.html",
            "queries": {
                "getrepinfo": {
                    "reputation": 100,
                    "country": "US",
                    "popularity": 5,
                    "age": 116,
                    "threathistory": 0,
                    "riskLevel": 5
                }
            }
        },
        "BeautifiedHtml": "<table class='cc-table horizontal-table'><tr><th>Type</th><th>Indicator</th><th>Reputation</th><th>Country</th><th>D3 Risk Level</th></tr><tr><td>url</td><td>https://docs.python.org/3/library/hashlib.html</td><td>100</td><td>US</td><td>5</td></tr></table>"
    }
]
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "url",
    "results": [
        {
            "url": "https://xmr.pool.minergate.com",
            "queries": {
                "getrepinfo": {
                    "reputation": 10,
                    "riskLevel": 1,
                    "country": "",
                    "popularity": 1,
                    "age": 4,
                    "threathistory": 1
                }
            }
        }
    ]
}
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
{
  "URLs": ["https://xmr.pool.minergate.com/"],
  "Reputations": [10],
  "RiskLevels": ["High"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url

queries

https://xmr.pool.minergate.com

{'getrepinfo': {'reputation': 10, 'riskLevel': 1, 'country': '', 'popularity': 1, 'age': 4, 'threathistory': 1}}

D3-defined Risk Levels

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 error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "file",
    "results": [
        {
            "md5": "*****",
            "hash": null,
            "queries": {
                "getinfo": {
                    "md5": "*****",
                    "hash": null,
                    "det": "B",
                    "detdate": 1378958091,
                    "filesize": 234496,
                    "fseen": 1378955978,
                    "malwaregroup": "Pua.Lyrics.Gen",
                    "pccount": 8
                }
            }
        },
        {
            "md5": null,
            "hash": "*****",
            "queries": {
                "getinfo": {
                    "md5": null,
                    "hash": "*****",
                    "det": "B",
                    "detdate": 1612994524,
                    "filesize": 204800,
                    "fseen": 1612993856,
                    "malwaregroup": "W32.Gen.BT",
                    "pccount": 0
                }
            }
        }
    ]
}
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
{
  "FileHashes": ["*****","*****"],
  "Determinations" ["B","B"],
  "malwareGroups": ["Pua.Lyrics.Gen","W32.Gen.BT"],
  "FirstSeenTime": ["2013-09-12T03:19:38Z","2013-10-11T23:40:59Z"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

file

results

{'md5': '*****', 'hash': None, 'queries': {'getinfo': {'md5': '*****', 'hash': None, 'det': 'B', 'detdate': 1378958091, 'filesize': 234496, 'fseen': 1378955978, 'malwaregroup': 'Pua.Lyrics.Gen', 'pccount': 8}}}

{'md5': None, 'hash': '*****', 'queries': {'getinfo': {'md5': None, 'hash': '*****', 'det': 'B', 'detdate': 1612994524, 'filesize': 204800, 'fseen': 1612993856, 'malwaregroup': 'W32.Gen.BT', 'pccount': 0}}}

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "localdb",
    "results": [
        {
            "localdb": "0|0|0|0",
            "queries": {
                "getipfile": {
                    "file_status": 201,
                    "file_msg": "Full files are returned",
                    "file_type": "ip_spam_sources",
                    "new_major": 1,
                    "new_minor": 4349,
                    "new_md5": "*****",
                    "files": [
                        {
                            "order": 1,
                            "name": "wr_ip_SpamSources_1_4349.txt",
                            "md5": "*****",
                            "location": "https://localdb-ip-daily.brightcloud.com/wr_ip_SpamSources_1_4349.txt?response-content-language=*****+*****+usEU4t4z/*****=&Expires=1661212619&Signature=*****-c420-*****~*****~*****-*****~*****-*****&Key-Pair-Id=*****"
                        }
                    ],
                    "update_status": 201,
                    "update_msg": "Full files are returned",
                    "ip_updates": [
                        {
                            "order": 1,
                            "name": "update_1.4349_1.txt",
                            "md5": "*****",
                            "location": "https://localdb-ip-rtu.brightcloud.com/update_1.4349_1.txt?response-content-language=*****/mv7P2brLPo+*****+*****=&Expires=1661212410&Signature=*****~*****-*****-*****~*****~*****-*****-*****~*****-*****-*****&Key-Pair-Id=*****"
                        },
                        {
                            "order": 2,
                            "name": "update_1.4349_2.txt",
                            "md5": "*****",
                            "location": "https://localdb-ip-rtu.brightcloud.com/update_1.4349_2.txt?response-content-language=/*****+*****+*****+*****/*****+/*****=&Expires=1661212410&Signature=*****-*****-*****~*****-*****~*****-*****~*****-*****-*****&Key-Pair-Id=*****"
                        },
                        {
                            "order": 3,
                            "name": "update_1.4349_3.txt",
                            "md5": "*****",
                            "location": "https://localdb-ip-rtu.brightcloud.com/update_1.4349_3.txt?response-content-language=*****/tNH+*****/*****/*****/*****=&Expires=1661212410&Signature=*****-*****~*****-*****~*****-*****-*****&Key-Pair-Id=*****"
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "FileType": "ip_spam_sources",
  "FileMessage" "Full files are returned"
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

localdb

results

{'localdb': '0|0|0|0', 'queries': {'getipfile': {'file_status': 201, 'file_msg': 'Full files are returned', 'file_type': 'ip_spam_sources', 'new_major': 1, 'new_minor': 4349, 'new_md5': '*****', 'files': [{'order': 1, 'name': 'wr_ip_SpamSources_1_4349.txt', 'md5': '*****', 'location': 'https://localdb-ip-daily.brightcloud.com/wr_ip_SpamSources_1_4349.txt?response-content-language=*****+*****+usEU4t4z/*****=&Expires=1661212619&Signature=*****-c420-*****~*****~*****-*****~*****-*****&Key-Pair-Id=*****'}], 'update_status': 201, 'update_msg': 'Full files are returned', 'ip_updates': [{'order': 1, 'name': 'update_1.4349_1.txt', 'md5': '*****', 'location': 'https://localdb-ip-rtu.brightcloud.com/update_1.4349_1.txt?response-content-language=*****/mv7P2brLPo+*****+*****=&Expires=1661212410&Signature=*****~*****-*****-*****~Zd~*****-*****-*****~*****-*****-*****&Key-Pair-Id=*****'}, {'order': 2, 'name': 'update_1.4349_2.txt', 'md5': '*****', 'location': 'https://localdb-ip-rtu.brightcloud.com/update_1.4349_2.txt?response-content-language=/*****+*****+*****+*****/*****+/*****=&Expires=1661212410&Signature=*****-*****-*****~*****-*****~*****-*****~*****-*****-*****&Key-Pair-Id=*****'}, {'order': 3, 'name': 'update_1.4349_3.txt', 'md5': '*****', 'location': 'https://localdb-ip-rtu.brightcloud.com/update_1.4349_3.txt?response-content-language=*****/tNH+*****/*****/*****/*****=&Expires=1661212410&Signature=*****-*****~*****-*****~*****-*****-*****&Key-Pair-Id=*****'}]}}}

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "requestid": "*****",
    "type": "ip",
    "results": [
        {
            "ip": "*****",
            "queries": {
                "getgeofile": {
                    "status": 200,
                    "statusmsg": "OK",
                    "geolocation": "https://geofile1.brightcloud.com/webroot_v1114_20220901_small.csv.zip?response-content-language=*****+*****/*****/*****/*****=&Expires=1662756499&Signature=*****~*****~*****~*****-*****~*****-*****-*****-*****~*****&Key-Pair-Id=*****",
                    "geochecksum": "*****",
                    "geoversion": "11.14"
                }
            }
        }
    ]
}
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
{
  "FileType": "ip",
  "CurrentGeoFile": "*****",
  "GeoFileLocation": "https://geofile1.brightcloud.com/webroot_v1114_20220901_small.csv.zip?response-content-language=*****+*****+*****/*****/*****=&Expires=1662755852&Signature=*****-*****~*****~*****~*****~*****-*****~*****-*****~*****&Key-Pair-Id=*****",
  "NewGeoFileVersion": "11.14",
  "StatusMessage": "OK"
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

requestid

*****

type

ip

results

{'ip': '*****', 'queries': {'getgeofile': {'status': 200, 'statusmsg': 'OK', 'geolocation': 'https://geofile1.brightcloud.com/webroot_v1114_20220901_small.csv.zip?response-content-language=*****+*****/*****/*****/*****=&Expires=1662756499&Signature=*****~*****~*****~*****-*****~k-*****-*****-*****~*****&Key-Pair-Id=*****', 'geochecksum': '*****', 'geoversion': '11.14'}}}

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "requestid": "*****",
    "type": "ip",
    "results": [
        {
            "ip": "***.***.***.***",
            "queries": {
                "getgeoinfo": {
                    "country": "united states",
                    "region": "southwest",
                    "state": "california",
                    "city": "mountain view",
                    "latitude": "37.41916",
                    "longitude": "-122.07541",
                    "organization": "google",
                    "carrier": "google llc",
                    "tld": "net",
                    "sld": "1e100",
                    "asn": "15169"
                }
            }
        },
        {
            "ip": "***:***:***:***:***:***:***:***",
            "queries": {
                "getgeoinfo": {
                    "country": "canada",
                    "region": "central canada",
                    "state": "quebec",
                    "city": "montreal",
                    "latitude": "45.52",
                    "longitude": "-73.57",
                    "organization": "ovh hosting  inc.",
                    "carrier": null,
                    "tld": null,
                    "sld": null,
                    "asn": null
                }
            }
        }
    ]
}
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
{
  "IPs": ["***.***.***.***","***:***:***:***:***:***:***:***"],
  "Countries" [ "united states", "canada" ],
  "StatesOrProvinces": ["california","quebec"],
  "Cities": [ "mountain view", "montreal" ],
  "Organizations": [ "google", "ovh hosting  inc." ],
  "ASNs": ["15169",null]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

requestid

*****

type

ip

results

{'ip': '***.***.***.***', 'queries': {'getgeoinfo': {'country': 'united states', 'region': 'southwest', 'state': 'california', 'city': 'mountain view', 'latitude': '37.41916', 'longitude': '-122.07541', 'organization': 'google', 'carrier': 'google llc', 'tld': 'net', 'sld': '1e100', 'asn': '15169'}}}

{'ip': '***:***:***:***:***:***:***:***', 'queries': {'getgeoinfo': {'country': 'canada', 'region': 'central canada', 'state': 'quebec', 'city': 'montreal', 'latitude': '45.52', 'longitude': '-73.57', 'organization': 'ovh hosting inc.', 'carrier': None, 'tld': None, 'sld': None, 'asn': None}}}

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "ip",
    "results": [
        {
            "ip": "***.***.***.***",
            "queries": {
                "getrephistory": {
                    "max_reputation": 95,
                    "min_reputation": 15,
                    "avg_reputation": 53,
                    "history_count": 4,
                    "history": [
                        {
                            "ts": 1613696464,
                            "reputation": 90
                        },
                        {
                            "ts": 1613091656,
                            "reputation": 15
                        },
                        {
                            "ts": 1610672467,
                            "reputation": 95
                        },
                        {
                            "ts": 1610067661,
                            "reputation": 15
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "IPs": ["***.***.***.***","***.***.***.***"],
  "MaxReputations": [95,95],
  "MinReputations": [5,15],
  "AverageReputations": [16,53],
  "HistoryCounts": [1064,4]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

ip

results

{'ip': '***.***.***.***', 'queries': {'getrephistory': {'max_reputation': 95, 'min_reputation': 15, 'avg_reputation': 53.0, 'history_count': 4, 'history': [{'ts': 1613696464, 'reputation': 90}, {'ts': 1613091656, 'reputation': 15}, {'ts': 1610672467, 'reputation': 95}, {'ts': 1610067661, 'reputation': 15}]}}}

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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 error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "url",
    "results": [
        {
            "url": "getcatlist",
            "queries": {
                "getcatlist": {
                    "cats": [
                        {
                            "catid": 1,
                            "catname": "Real Estate",
                            "catgroup": "Productivity"
                        },
                        {
                            "catid": 2,
                            "catname": "Computer and Internet Security",
                            "catgroup": "Productivity"
                        },
                        {
                            "catid": 3,
                            "catname": "Financial Services",
                            "catgroup": "Privacy"
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "CategoryIds": [0,1],
  "CategoryNames": [ "Real Estate", "Computer and Internet Security" ],
  "CategoryGroups": ["Productivity","Productivity"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

url

results

{'url': 'getcatlist', 'queries': {'getcatlist': {'cats': [{'catid': 1, 'catname': 'Real Estate', 'catgroup': 'Productivity'}, {'catid': 2, 'catname': 'Computer and Internet Security', 'catgroup': 'Productivity'}, {'catid': 3, 'catname': 'Financial Services', 'catgroup': 'Privacy'}]}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

JSON
[
    "https://www.google.com",
    "https://xmr.pool.minergate.com"
]

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": "url",
    "results": [
        {
            "url": "https://www.google.com",
            "queries": {
                "getinfo": {
                    "a1cat": 0,
                    "reputation": 81,
                    "lcp": "google.com",
                    "cats": [
                        {
                            "catid": 50,
                            "catname": "Search Engines",
                            "catgroup": "Productivity",
                            "conf": 100
                        }
                    ]
                }
            }
        },
        {
            "url": "https://xmr.pool.minergate.com",
            "queries": {
                "getinfo": {
                    "a1cat": 1,
                    "reputation": 10,
                    "lcp": "pool.minergate.com",
                    "cats": [
                        {
                            "catid": 56,
                            "catname": "Malware Sites",
                            "catgroup": "Security",
                            "conf": 70
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "URLs": ["https://www.google.com","https://xmr.pool.minergate.com"],
  "Reputations": [81,10],
  "CategoryIds": [50,56],
  "CategoryNames": [ "Search Engines", "Malware Sites" ],
  "CategoryGroups": ["Productivity","Security"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

url

results

{'url': 'https://www.google.com', 'queries': {'getinfo': {'a1cat': 0, 'reputation': 81, 'lcp': 'google.com', 'cats': [{'catid': 50, 'catname': 'Search Engines', 'catgroup': 'Productivity', 'conf': 100}]}}}

{'url': 'https://xmr.pool.minergate.com', 'queries': {'getinfo': {'a1cat': 1, 'reputation': 10, 'lcp': 'pool.minergate.com', 'cats': [{'catid': 56, 'catname': 'Malware Sites', 'catgroup': 'Security', 'conf': 70}]}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

Input

Input Parameter

Required/Optional

Description

Example

URLs

Required

The URLs used to obtain WHOIS information.

JSON
[
    "https://www.google.com",
    "https://xmr.pool.minergate.com"
]

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": "url",
    "results": [
        {
            "url": "https://www.google.com",
            "queries": {
                "getwhoisinfofull": {
                    "domainname": "google.com",
                    "audit_auditupdateddate": "2022-08-20",
                    "contactemail": "select request email form at https://*****.*****.***/*****",
                    "createddate": "1997-09-15",
                    "expiresdate": "2028-09-14",
                    "nameservers": "ns1.google.com, ns3.google.com, ns4.google.com, ns2.google.com",
                    "registrarname": "markmonitor, inc.",
                    "standardregcreateddate": "1997-09-15 00:00:00 UTC",
                    "standardregexpiresdate": "2028-09-14 00:00:00 UTC",
                    "standardregupdateddate": "2019-09-09 00:00:00 UTC",
                    "status": "clientupdateprohibited (https://www.icann.org/epp#clientupdateprohibited), clienttransferprohibited (https://www.icann.org/epp#clienttransferprohibited), clientdeleteprohibited (https://www.icann.org/epp#clientdeleteprohibited), serverupdateprohibited (https://www.icann.org/epp#serverupdateprohibited), servertransferprohibited (https://www.icann.org/epp#servertransferprohibited), serverdeleteprohibited (https://www.icann.org/epp#serverdeleteprohibited)",
                    "updateddate": "2019-09-09",
                    "whoisserver": "whois.markmonitor.com",
                    "administrativecontact_city": "",
                    "administrativecontact_country": "us",
                    "administrativecontact_email": "select request email form at https://*****.*****.***/*****",
                    "administrativecontact_fax": "",
                    "administrativecontact_faxext": "",
                    "administrativecontact_name": "",
                    "administrativecontact_organization": "google llc",
                    "administrativecontact_postalcode": "",
                    "administrativecontact_state": "ca",
                    "administrativecontact_street1": "",
                    "administrativecontact_street2": "",
                    "administrativecontact_street3": "",
                    "administrativecontact_street4": "",
                    "administrativecontact_telephone": "",
                    "administrativecontact_telephoneext": "",
                    "registrant_city": "",
                    "registrant_country": "us",
                    "registrant_email": "select request email form at https://*****.*****.***/*****",
                    "registrant_fax": "",
                    "registrant_faxext": "",
                    "registrant_name": "",
                    "registrant_organization": "google llc",
                    "registrant_postalcode": "",
                    "registrant_state": "ca",
                    "registrant_street1": "",
                    "registrant_street2": "",
                    "registrant_street3": "",
                    "registrant_street4": "",
                    "registrant_telephone": "",
                    "registrant_telephoneext": ""
                }
            }
        },
        {
            "url": "https://xmr.pool.minergate.com",
            "queries": {
                "getwhoisinfofull": {
                    "domainname": "minergate.com",
                    "audit_auditupdateddate": "2022-08-19",
                    "contactemail": "select contact domain holder link at https://www.*****.*****.***/*****",
                    "createddate": "2014-03-04",
                    "expiresdate": "2023-03-04",
                    "nameservers": "ns-822.awsdns-38.net, ns-1810.awsdns-34.co.uk, ns-97.awsdns-12.com, ns-1476.awsdns-56.org",
                    "registrarname": "godaddy.com, llc",
                    "standardregcreateddate": "2014-03-04 00:00:00 UTC",
                    "standardregexpiresdate": "2023-03-04 00:00:00 UTC",
                    "standardregupdateddate": "2022-02-28 00:00:00 UTC",
                    "status": "clienttransferprohibited https://icann.org/epp#clienttransferprohibited, clientupdateprohibited https://icann.org/epp#clientupdateprohibited, clientrenewprohibited https://icann.org/epp#clientrenewprohibited, clientdeleteprohibited https://icann.org/epp#clientdeleteprohibited",
                    "updateddate": "2022-02-28",
                    "whoisserver": "whois.godaddy.com",
                    "administrativecontact_city": "tempe",
                    "administrativecontact_country": "us",
                    "administrativecontact_email": "select contact domain holder link at https://www.*****.*****.***/*****",
                    "administrativecontact_fax": "+1.4806242598",
                    "administrativecontact_faxext": "",
                    "administrativecontact_name": "registration private",
                    "administrativecontact_organization": "domains by proxy, llc",
                    "administrativecontact_postalcode": "*****",
                    "administrativecontact_state": "arizona",
                    "administrativecontact_street1": "domainsbyproxy.com, 2155 e warner rd",
                    "administrativecontact_street2": "",
                    "administrativecontact_street3": "",
                    "administrativecontact_street4": "",
                    "administrativecontact_telephone": "*****",
                    "administrativecontact_telephoneext": "",
                    "registrant_city": "tempe",
                    "registrant_country": "us",
                    "registrant_email": "select contact domain holder link at https://www.*****.*****.***/*****",
                    "registrant_fax": "+1.4806242598",
                    "registrant_faxext": "",
                    "registrant_name": "registration private",
                    "registrant_organization": "domains by proxy, llc",
                    "registrant_postalcode": "*****",
                    "registrant_state": "arizona",
                    "registrant_street1": "domainsbyproxy.com, 2155 e warner rd",
                    "registrant_street2": "",
                    "registrant_street3": "",
                    "registrant_street4": "",
                    "registrant_telephone": "*****",
                    "registrant_telephoneext": ""
                }
            }
        }
    ]
}
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
{
  "URLs": ["https://www.google.com","https://xmr.pool.minergate.com"],
  "registrarNames": [ "markmonitor, inc.", "godaddy.com, llc" ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

url

results

{'url': 'https://www.google.com', 'queries': {'getwhoisinfofull': {'domainname': 'google.com', 'audit_auditupdateddate': '2022-08-20', 'contactemail': 'select request email form at https://*****.*****.***/*****', 'createddate': '1997-09-15', 'expiresdate': '2028-09-14', 'nameservers': 'ns1.google.com, ns3.google.com, ns4.google.com, ns2.google.com', 'registrarname': 'markmonitor, inc.', 'standardregcreateddate': '1997-09-15 00:00:00 UTC', 'standardregexpiresdate': '2028-09-14 00:00:00 UTC', 'standardregupdateddate': '2019-09-09 00:00:00 UTC', 'status': 'clientupdateprohibited (https://www.icann.org/epp#clientupdateprohibited), clienttransferprohibited (https://www.icann.org/epp#clienttransferprohibited), clientdeleteprohibited (https://www.icann.org/epp#clientdeleteprohibited), serverupdateprohibited (https://www.icann.org/epp#serverupdateprohibited), servertransferprohibited (https://www.icann.org/epp#servertransferprohibited), serverdeleteprohibited (https://www.icann.org/epp#serverdeleteprohibited)', 'updateddate': '2019-09-09', 'whoisserver': 'whois.markmonitor.com', 'administrativecontact_city': '', 'administrativecontact_country': 'us', 'administrativecontact_email': 'select request email form at https://*****.*****.***/*****', 'administrativecontact_fax': '', 'administrativecontact_faxext': '', 'administrativecontact_name': '', 'administrativecontact_organization': 'google llc', 'administrativecontact_postalcode': '', 'administrativecontact_state': 'ca', 'administrativecontact_street1': '', 'administrativecontact_street2': '', 'administrativecontact_street3': '', 'administrativecontact_street4': '', 'administrativecontact_telephone': '', 'administrativecontact_telephoneext': '', 'registrant_city': '', 'registrant_country': 'us', 'registrant_email': 'select request email form at https://*****.*****.***/*****', 'registrant_fax': '', 'registrant_faxext': '', 'registrant_name': '', 'registrant_organization': 'google llc', 'registrant_postalcode': '', 'registrant_state': 'ca', 'registrant_street1': '', 'registrant_street2': '', 'registrant_street3': '', 'registrant_street4': '', 'registrant_telephone': '', 'registrant_telephoneext': ''}}}

{'url': 'https://xmr.pool.minergate.com', 'queries': {'getwhoisinfofull': {'domainname': 'minergate.com', 'audit_auditupdateddate': '2022-08-19', 'contactemail': 'select contact domain holder link at https://www.*****.*****.***/*****', 'createddate': '2014-03-04', 'expiresdate': '2023-03-04', 'nameservers': 'ns-822.awsdns-38.net, ns-1810.awsdns-34.co.uk, ns-97.awsdns-12.com, ns-1476.awsdns-56.org', 'registrarname': 'godaddy.com, llc', 'standardregcreateddate': '2014-03-04 00:00:00 UTC', 'standardregexpiresdate': '2023-03-04 00:00:00 UTC', 'standardregupdateddate': '2022-02-28 00:00:00 UTC', 'status': 'clienttransferprohibited https://icann.org/epp#clienttransferprohibited, clientupdateprohibited https://icann.org/epp#clientupdateprohibited, clientrenewprohibited https://icann.org/epp#clientrenewprohibited, clientdeleteprohibited https://icann.org/epp#clientdeleteprohibited', 'updateddate': '2022-02-28', 'whoisserver': 'whois.godaddy.com', 'administrativecontact_city': 'tempe', 'administrativecontact_country': 'us', 'administrativecontact_email': 'select contact domain holder link at https://www.*****.*****.***/*****', 'administrativecontact_fax': '+1.4806242598', 'administrativecontact_faxext': '', 'administrativecontact_name': 'registration private', 'administrativecontact_organization': 'domains by proxy, llc', 'administrativecontact_postalcode': '*****', 'administrativecontact_state': 'arizona', 'administrativecontact_street1': 'domainsbyproxy.com, 2155 e warner rd', 'administrativecontact_street2': '', 'administrativecontact_street3': '', 'administrativecontact_street4': '', 'administrativecontact_telephone': '*****', 'administrativecontact_telephoneext': '', 'registrant_city': 'tempe', 'registrant_country': 'us', 'registrant_email': 'select contact domain holder link at https://www.*****.*****.***/*****', 'registrant_fax': '+1.4806242598', 'registrant_faxext': '', 'registrant_name': 'registration private', 'registrant_organization': 'domains by proxy, llc', 'registrant_postalcode': '*****', 'registrant_state': 'arizona', 'registrant_street1': 'domainsbyproxy.com, 2155 e warner rd', 'registrant_street2': '', 'registrant_street3': '', 'registrant_street4': '', 'registrant_telephone': '*****', 'registrant_telephoneext': ''}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "localdb",
    "results": [
        {
            "localdb": "5|0|0|0",
            "queries": {
                "geturlfile": {
                    "file_status": 201,
                    "file_msg": "Full files are returned",
                    "file_type": "url_rep_1m",
                    "new_major": 8,
                    "new_minor": 341,
                    "new_md5": "*****",
                    "files": [
                        {
                            "order": 1,
                            "name": "full_bcdb_rep_1m_8.341.bin",
                            "md5": "*****",
                            "location": "https://localdb-url-daily.brightcloud.com/*****"
                        }
                    ],
                    "update_status": 201,
                    "update_msg": "Full files are returned",
                    "url_updates": [
                        {
                            "order": 1,
                            "contentlocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "contentchecksum": "*****",
                            "replocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "repchecksum": "*****"
                        },
                        {
                            "order": 2,
                            "contentlocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "contentchecksum": "*****",
                            "replocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "repchecksum": "*****"
                        },
                        {
                            "order": 3,
                            "contentlocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "contentchecksum": "*****",
                            "replocation": "https://localdb-url-rtu.brightcloud.com/*****",
                            "repchecksum": "*****"
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "FileType": "url_rep_1m",
  "FileMessage": "Full files are returned"
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

localdb

results

{'localdb': '5|0|0|0', 'queries': {'geturlfile': {'file_status': 201, 'file_msg': 'Full files are returned', 'file_type': 'url_rep_1m', 'new_major': 8, 'new_minor': 341, 'new_md5': '*****', 'files': [{'order': 1, 'name': 'full_bcdb_rep_1m_8.341.bin', 'md5': '*****', 'location': 'https://localdb-url-daily.brightcloud.com/*****'}], 'update_status': 201, 'update_msg': 'Full files are returned', 'url_updates': [{'order': 1, 'contentlocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'contentchecksum': '*****', 'replocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'repchecksum': '*****'}, {'order': 2, 'contentlocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'contentchecksum': '*****', 'replocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'repchecksum': '*****'}, {'order': 3, 'contentlocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'contentchecksum': '*****', 'replocation': 'https://localdb-url-rtu.brightcloud.com/*****', 'repchecksum': '*****'}]}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "requestid": "*****",
    "type": "ip",
    "results": [
        {
            "ip": "*****",
            "queries": {
                "getv6geofile": {
                    "status": 200,
                    "statusmsg": "OK",
                    "geolocation": "https://geofile1.brightcloud.com/*****",
                    "geochecksum": "*****",
                    "geoversion": "11.14"
                }
            }
        }
    ]
}
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
{
  "FileType": "ip",
  "CurrentGeoFile": "*****",
  "GeoFileLocation": "https://geofile1.brightcloud.com/*****",
  "NewGeoFileVersion": "11.14",
  "StatusMessage": "OK"
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

requestid

*****

type

ip

results

{'ip': '*****', 'queries': {'getv6geofile': {'status': 200, 'statusmsg': 'OK', 'geolocation': 'https://geofile1.brightcloud.com/*****', 'geochecksum': '*****', 'geoversion': '11.14'}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "requestid": "*****",
    "type": "ip",
    "results": [
        {
            "ip": "***.***.***.***",
            "queries": {
                "getthreathistory": {
                    "threat_count": 3,
                    "history": [
                        {
                            "ts": 1615748551,
                            "is_threat": 1,
                            "threat_types": [
                                "phishing"
                            ]
                        },
                        {
                            "ts": 1615446006,
                            "is_threat": 0,
                            "threat_types": null
                        },
                        {
                            "ts": 1614643805,
                            "is_threat": 1,
                            "threat_types": [
                                "spam sources"
                            ]
                        },
                        {
                            "ts": 1607842809,
                            "is_threat": 0,
                            "threat_types": null
                        },
                        {
                            "ts": 1607704224,
                            "is_threat": 1,
                            "threat_types": [
                                "scanners"
                            ]
                        }
                    ]
                }
            }
        }
    ]
}
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
{
  "IPs": ["***.***.***.***","***.***.***.***"],
  "ThreatCounts": [3,6]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

requestid

*****

type

ip

results

{'ip': '***.***.***.***', 'queries': {'getthreathistory': {'threat_count': 3, 'history': [{'ts': 1615748551, 'is_threat': 1, 'threat_types': ['phishing']}, {'ts': 1615446006, 'is_threat': 0, 'threat_types': None}, {'ts': 1614643805, 'is_threat': 1, 'threat_types': ['spam sources']}, {'ts': 1607842809, 'is_threat': 0, 'threat_types': None}, {'ts': 1607704224, 'is_threat': 1, 'threat_types': ['scanners']}]}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

JSON
[
    "https://www.google.com",
    "https://xmr.pool.minergate.com"
]

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": "url",
    "results": [
        {
            "url": "https://www.google.com",
            "queries": {
                "getwhoisinfo": {
                    "domainname": "google.com",
                    "audit_auditupdateddate": "2022-09-05",
                    "contactemail": "select request email form at https://*****.*****.***/*****",
                    "createddate": "1997-09-15",
                    "expiresdate": "2028-09-14",
                    "nameservers": "ns1.google.com, ns4.google.com, ns2.google.com, ns3.google.com",
                    "registrarname": "markmonitor, inc.",
                    "standardregcreateddate": "1997-09-15 00:00:00 UTC",
                    "standardregexpiresdate": "2028-09-14 00:00:00 UTC",
                    "standardregupdateddate": "2019-09-09 00:00:00 UTC",
                    "registrant_city": "",
                    "registrant_country": "us",
                    "registrant_email": "select request email form at https://*****.*****.***/*****",
                    "registrant_name": "",
                    "registrant_organization": "google llc",
                    "registrant_postalcode": "",
                    "registrant_state": "ca",
                    "registrant_street1": "",
                    "registrant_telephone": ""
                }
            }
        },
        {
            "url": "https://xmr.pool.minergate.com",
            "queries": {
                "getwhoisinfo": {
                    "domainname": "minergate.com",
                    "audit_auditupdateddate": "2022-08-28",
                    "contactemail": "select contact domain holder link at https://www.*****.*****.***/*****",
                    "createddate": "2014-03-04",
                    "expiresdate": "2023-03-04",
                    "nameservers": "ns-822.awsdns-38.net, ns-1810.awsdns-34.co.uk, ns-97.awsdns-12.com, ns-1476.awsdns-56.org",
                    "registrarname": "godaddy.com, llc",
                    "standardregcreateddate": "2014-03-04 00:00:00 UTC",
                    "standardregexpiresdate": "2023-03-04 00:00:00 UTC",
                    "standardregupdateddate": "2022-02-28 00:00:00 UTC",
                    "registrant_city": "tempe",
                    "registrant_country": "us",
                    "registrant_email": "select contact domain holder link at https://www.*****.*****.***/*****",
                    "registrant_name": "registration private",
                    "registrant_organization": "domains by proxy, llc",
                    "registrant_postalcode": "*****",
                    "registrant_state": "arizona",
                    "registrant_street1": "domainsbyproxy.com, 2155 e warner rd",
                    "registrant_telephone": "*****"
                }
            }
        }
    ]
}
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
{
  "URLs": ["https://www.google.com","https://xmr.pool.minergate.com"],
  "DomainNames": ["google.com","minergate.com"],
  "RegistrarNames": [ "markmonitor, inc.", "godaddy.com, llc" ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

url

results

{'url': 'https://www.google.com', 'queries': {'getwhoisinfo': {'domainname': 'google.com', 'audit_auditupdateddate': '2022-09-05', 'contactemail': 'select request email form at https://*****.*****.***/*****', 'createddate': '1997-09-15', 'expiresdate': '2028-09-14', 'nameservers': 'ns1.google.com, ns4.google.com, ns2.google.com, ns3.google.com', 'registrarname': 'markmonitor, inc.', 'standardregcreateddate': '1997-09-15 00:00:00 UTC', 'standardregexpiresdate': '2028-09-14 00:00:00 UTC', 'standardregupdateddate': '2019-09-09 00:00:00 UTC', 'registrant_city': '', 'registrant_country': 'us', 'registrant_email': 'select request email form at https://*****.*****.***/*****', 'registrant_name': '', 'registrant_organization': 'google llc', 'registrant_postalcode': '', 'registrant_state': 'ca', 'registrant_street1': '', 'registrant_telephone': ''}}}

{'url': 'https://xmr.pool.minergate.com', 'queries': {'getwhoisinfo': {'domainname': 'minergate.com', 'audit_auditupdateddate': '2022-08-28', 'contactemail': 'select contact domain holder link at https://www.*****.*****.***/*****', 'createddate': '2014-03-04', 'expiresdate': '2023-03-04', 'nameservers': 'ns-822.awsdns-38.net, ns-1810.awsdns-34.co.uk, ns-97.awsdns-12.com, ns-1476.awsdns-56.org', 'registrarname': 'godaddy.com, llc', 'standardregcreateddate': '2014-03-04 00:00:00 UTC', 'standardregexpiresdate': '2023-03-04 00:00:00 UTC', 'standardregupdateddate': '2022-02-28 00:00:00 UTC', 'registrant_city': 'tempe', 'registrant_country': 'us', 'registrant_email': 'select contact domain holder link at https://www.*****.*****.***/*****', 'registrant_name': 'registration private', 'registrant_organization': 'domains by proxy, llc', 'registrant_postalcode': '*****', 'registrant_state': 'arizona', 'registrant_street1': 'domainsbyproxy.com, 2155 e warner rd', 'registrant_telephone': '*****'}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.

JSON
[
    "email@provider.com"
]

URLs

Required

The URLs to be reclassified.

JSON
[
    "https://www.d3test1.com/path?query",
    "https://www.d3test2.com/path?query"
]

Categories

Optional

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.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": 200,
    "type": "url",
    "results": [
        {
            "url": "submitnewuricats",
            "queries": {
                "submitnewuricats": {
                    "success": 1,
                    "changerequestticket": "*****"
                }
            }
        }
    ]
}
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
{
  "ChangeRequestTicket": "*****"
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

200

type

url

results

{'url': 'submitnewuricats', 'queries': {'submitnewuricats': {'success': 1, 'changerequestticket': '*****'}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab 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.