MXToolBox

Overview

MXToolbox is a free-to-use tool that offers a convenient way to check website and server issues with the help of its fast and accurate network consisting of diagnostic and lookup tools.

D3 SOAR is providing REST operations to function with MXToolBox.

MXToolBox is available for use in:

D3 SOAR	V12.7.83.0+
Category	Threat Intelligence
Deployment Options	Option II, Option IV

Known Limitations

Each paid plan has a daily limit for both simple and complex lookups. This limit applies to how many lookups you are allowed to request.

You can see your limits on the API Page or by running the API Usage call also found on that page.

If you upgrade your account, you do not need to revoke your API key. Contact the MxToolbox Sales Team to discuss increasing your daily limit or to ask any questions.

Connection

To connect to MXToolBox from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the MXToolBox API.	https://mxtoolbox.com
Authorization Token	The authorization token to authenticate the API connection.	9*************************************c
API Version	The version of the API to use for the connection.	v1

Permission Requirements

Each endpoint in the MXToolBox API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required API Quotas
Lookup A Record	DNS Request Quota
Lookup DNS Record	DNS Request Quota
Lookup IP in Blacklist	Network Request Quota (paid plan required)
Lookup MX Record	DNS Request Quota
Lookup PTR Record	DNS Request Quota
Lookup SOAR Record	DNS Request Quota
Lookup SPF Record	DNS Request Quota
Lookup TXT Record	DNS Request Quota

As MXToolBox is using role-based access control (RBAC), the authorization token is generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account plan. Users need to configure their user profile from the MXToolBox console for each command in this integration.

Reader Note

MXToolBox provides both free and paid versions of their service. The free version includes a DNS request quota for API access, subject to a rate limit. However, a subscription to a paid plan is required to access the network request quota of their API. For detailed information on pricing plans, please visit https://mxtoolbox.com/public/upgradev2.aspx?feature=mxrest.

Configuring MXToolBox to Work with D3 SOAR

Open your web browser and navigate to https://mxtoolbox.com/.
Once the page is loaded, locate and click on the Login button.
If you already have an account, sign in with your credentials. However, if you are a new user, choose the Sign up option and follow the provided instructions to create your account. After successfully setting up your account, log in using your new credentials.
Upon logging in, find your account email address displayed near the top right corner of the screen and click on it. This action will bring up a dropdown menu. From this menu, select Settings.
On the Settings page, navigate to the API tab, where you will find your unique API key. Copy and store the key in a secure location, as it will be required to create the connection in D3 SOAR.

Configuring D3 SOAR to Work with MXToolBox

Log in to D3 SOAR.
Find the MXToolBox integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type MXToolBox 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.
Configure the following fields to create a connection to MXToolBox.
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: 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://mxtoolbox.com.
  2. Copy and paste the API Key from the MXToolBox platform (Refer to step 5 of Configuring MXToolBox to Work with D3 SOAR).
  3. Input the API Version. The default value is v1.
10. 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.
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.
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

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

Integration API Note

For more information about the MXToolBox API, please refer to the MXToolBox API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring MXToolBox to Work with D3 SOAR for details.

Lookup A Record

Looks up DNS records for the given host names.

Reader Note

Providing an invalid host name input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

Host Names

Required

The host names to look up DNS records.

[

"example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "a",
        "IsTransitioned": false,
        "CommandArgument": "example.com",
        "TimeRecorded": "2022-01-05T14:15:19.9429652-06:00",
        "ReportingNameServer": "b.iana-*****.net",
        "TimeToComplete": "74",
        "RelatedIP": null,
        "ResourceRecordType": 1,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": 506,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/a/DNS-Record-Published?page=prob_a&showlogin=1&hidetoc=1&action=a:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Type": "A",
                "Domain Name": "example.com",
                "IP Address": "1.1.1.1",
                "TTL": "24 hrs",
                "Asn": "[{\"asname\":\"MCI Communications Services, Inc. d/b/a Verizon Business\", \"asn\":\"*****\"}]",
                "IsIpV6": "False"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - a:example.com\r\n\r\n  1 h.gtld-servers.net 1.1.1.1 NON-AUTH 34 ms Received 2 Referrals , rcode=NO_ERROR   example.com.\*****\tIN\tNS\ta.iana-servers.net,example.com.\*****\tIN\tNS\tb.iana-servers.net,\r\n  2 b.iana-servers.net 199.43.133.53 AUTH 2 ms Received 1 Answers , rcode=NO_ERROR   example.com.\t86400\tIN\tA\t1.1.1.1,\r\nLookupServer 74ms\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/example.com",
                "Command": "dns",
                "CommandArgument": "example.com"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DNS Record Published\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

TYPE	DOMAIN NAME	IP ADDRESS	TTL	ASN	ISIPV6
A	example.com	1.1.1.1	24 hrs	[{"asname":"MCI Communications Services, Inc. d/b/a Verizon Business", "asn":"****"}]	False

Error Handling

If the Return Data is Partially Successful or 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.	Lookup A Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup a Record failed.

Status Code: 400.

Message: Name or service not known.

Lookup DNS Record

Looks up DNS records for the given domains.

Reader Note

Providing an invalid domain input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

Domains

Required

The domains to look up DNS records.

[

"example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "dns",
        "IsTransitioned": false,
        "CommandArgument": "example.com",
        "TimeRecorded": "2022-01-05T14:09:34.6508559-06:00",
        "ReportingNameServer": "a.iana-*****.net",
        "TimeToComplete": "418",
        "RelatedIP": null,
        "ResourceRecordType": 2,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [
            {
                "ID": *****,
                "Name": "DNS Primary Server Listed At Parent",
                "Info": "Primary Name Server Not Listed At Parent",
                "Url": "https://mxtoolbox.com/Problem/dns/DNS-Primary-Server-Listed-At-Parent?page=prob_dns&showlogin=1&hidetoc=1&action=dns:example.com",
                "PublicDescription": null,
                "AdditionalInfo": [
                    "ns.icann.org"
                ],
                "IsExcludedByUser": false
            }
        ],
        "Warnings": [],
        "Passed": [
            {
                "ID": ****,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/dns/DNS-Record-Published?page=prob_dns&showlogin=1&hidetoc=1&action=dns:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            },
            {
                "ID": *****,
                "Name": "DNS Bad Glue Detected",
                "Info": "No Bad Glue Detected",
                "Url": "https://mxtoolbox.com/Problem/dns/DNS-Bad-Glue-Detected?page=prob_dns&showlogin=1&hidetoc=1&action=dns:example.com",
                "PublicDescription": null,
                "AdditionalInfo": [
                    ""
                ],
                "IsExcludedByUser": false
            },
            {
                "ID": *****,
                "Name": "DNS At Least Two Servers",
                "Info": "At Least Two Name Servers Found",
                "Url": "https://mxtoolbox.com/Problem/dns/DNS-At-Least-Two-Servers?page=prob_dns&showlogin=1&hidetoc=1&action=dns:example.com",
                "PublicDescription": null,
                "AdditionalInfo": [
                    ""
                ],
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Type": "NS",
                "Domain Name": "a.iana-*****.net",
                "IP Address": "1.2.3.4",
                "TTL": "24 hrs",
                "Status": "[GREEN]",
                "Time (ms)": "2",
                "Auth": "[GREEN]",
                "Parent": "[GREEN]",
                "Local": "[GREEN]",
                "Asn": "[{\"asname\":\"ICANN\", \"asn\":\"*****\"}]",
                "IsIpV6": "False"
            },
            {
                "Type": "NS",
                "Domain Name": "b.iana-*****.net",
                "IP Address": "1.2.3.4",
                "TTL": "24 hrs",
                "Status": "[GREEN]",
                "Time (ms)": "3",
                "Auth": "[GREEN]",
                "Parent": "[GREEN]",
                "Local": "[GREEN]",
                "Asn": "[{\"asname\":\"ICANN\", \"asn\":\"26710\"}]",
                "IsIpV6": "False"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "TimeStamp": "\r\nLookupServer 418ms\r\n",
                "Depth": "1",
                "ServerName": "e.gtld-*****.net",
                "ServerIP": "11.1.1.1",
                "Authoritative": "NON-AUTH",
                "ElapsedTime": "3 ms",
                "Result": "Received 2 Referrals , rcode=NO_ERROR",
                "Question": "",
                "Answers": "example.com.\*****\tIN\tNS\ta.iana-servers.net,example.com.\*****\tIN\tNS\tb.iana-servers.net,"
            },
            {
                "TimeStamp": "",
                "Depth": "2",
                "ServerName": "a.iana-*****.net",
                "ServerIP": "1.1.1.1",
                "Authoritative": "AUTH",
                "ElapsedTime": "2 ms",
                "Result": "Received 2 Answers , rcode=NO_ERROR",
                "Question": "",
                "Answers": "example.com.\*****\tIN\tNS\ta.iana-servers.net,example.com.\*****\tIN\tNS\tb.iana-servers.net,"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/example.com",
                "Command": "a",
                "CommandArgument": "example.com"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DNS Record Published\\\",\\\"DNS Bad Glue Detected\\\",\\\"DNS At Least Two Servers\\\",\\\"DNS All Servers Responding\\\",\\\"DNS All Servers Authoritative\\\",\\\"DNS Local Parent Mismatch\\\",\\\"DNS Servers are on Different Subnets\\\",\\\"DNS Servers Have Public IP Addresses\\\",\\\"DNS SOA Serial Numbers Match\\\",\\\"DNS SOA Serial Number Format\\\",\\\"DNS SOA Refresh Value\\\",\\\"DNS SOA Retry Value\\\",\\\"DNS SOA Expire Value\\\",\\\"DNS SOA NXDOMAIN Value\\\",\\\"DNS Open Recursive Name Server\\\"]\""
}

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

Result

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

SAMPLE DATA

TYPE	DOMAIN NAME	IP ADDRESS	TTL	STATUS	TIME (MS)	AUTH	PARENT	LOCAL	ASN	ISIPV6
NS	a.iana-*****.net	1.1.1.1	24 hrs	[GREEN]	2	[GREEN]	[GREEN]	[GREEN]	[{"asname":"ICANN", "asn":"*****"}]	False
NS	b.iana-*****.net	1.2.3.4	24 hrs	[GREEN]	3	[GREEN]	[GREEN]	[GREEN]	[{"asname":"ICANN", "asn":"*****"}]	Fals

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.	Lookup DNS Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup DNS Record failed.

Status Code: 400.

Message: Name or service not known.

Lookup IP in Blacklist

Performs a blacklist lookup on the provided IP addresses.

Reader Note

Providing an invalid IP address input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

IP addresses

Required

The IP addresses to perform a blacklist lookup.

[

"2.2.2.2"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "2.2.2.2",
        "Command": "spf",
        "IsTransitioned": false,
        "CommandArgument": "2.2.2.2",
        "TimeRecorded": "2020-08-05T10:18:12.4368337-07:00",
        "ReportingNameServer": "a.iana-*****.net",
        "TimeToComplete": "252",
        "RelatedIP": null,
        "ResourceRecordType": 16,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "SPF Record Published",
                "Info": "SPF Record found",
                "Url": "https://mxtoolbox.com/Problem/spf/SPF-Record-Published?page=prob_spf&showlogin=1&hidetoc=1&action=spf:2.2.2.2",
                "PublicDescription": null,
                "IsExcludedByUser": false
            },
            {
                "ID": *****,
                "Name": "SPF Record Deprecated",
                "Info": "No deprecated records found",
                "Url": "https://mxtoolbox.com/Problem/spf/SPF-Record-Deprecated?page=prob_spf&showlogin=1&hidetoc=1&action=spf:2.2.2.2",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Prefix": "",
                "Type": "record",
                "Value": "txt",
                "PrefixDesc": "",
                "Description": "v=spf1 -all",
                "RecordNum": "1"
            },
            {
                "Prefix": "",
                "Type": "v",
                "Value": "spf1",
                "PrefixDesc": "",
                "Description": "The SPF record version",
                "RecordNum": null
            },
            {
                "Prefix": "-",
                "Type": "all",
                "Value": "",
                "PrefixDesc": "Fail",
                "Description": "Always matches. It goes at the end of your record.",
                "RecordNum": null
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - txt:2.2.2.2\r\n\r\n  1 a.gtld-servers.net 1.1.1.1 NON-AUTH 0 ms Received 2 Referrals , rcode=NO_ERROR   2.2.2.2.\*****\tIN\tNS\ta.iana-servers.net,2.2.2.2.\*****\tIN\tNS\tb.iana-servers.net,\r\n  2 a.iana-servers.net 1.2.3.4 AUTH 0 ms Received 1 Answers , rcode=NO_ERROR   2.2.2.2.\*****\tIN\tTXT\tv=spf1 -all,\r\nRecord returned is an RFC 4408 TXT record.\r\nMAIL FROM: \r\nRETURN-PATH: \r\n\r\n- - Ranges\r\n\r\n- - Subqueries\r\n\r\n\r\n- - Results\r\nTXT:2.2.2.2 = Fail\r\nLookupServer 252ms\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/2.2.2.2",
                "Command": "a",
                "CommandArgument": "2.2.2.2"
            },
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/2.2.2.2",
                "Command": "dns",
                "CommandArgument": "2.2.2.2"
            },
            {
                "Name": "mx lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/mx/2.2.2.2",
                "Command": "mx",
                "CommandArgument": "2.2.2.2"
            },
            {
                "Name": "dns propagation",
                "URL": "https://mxtoolbox.com/api/v1/lookup/spf/2.2.2.2:all",
                "Command": "spf",
                "CommandArgument": "2.2.2.2:all"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"blacklist\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DNS Record Published\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

TYPE	IP ADDRESS	DOMAIN NAME	TTL	ASN	ISIPV6
PTR	2.2.2.2	dns.google	24 hrs	[{"asname":"Google LLC", "asn":"***"},{"asname":"Level 3 Parent, LLC", "asn":"***"}]	False

Error Handling

If the Return Data is Partially Successful or 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.	Lookup IP in Blacklist 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup IP in Blacklist failed.

Status Code: 400.

Message: Name or service not known.

Lookup MX Record

Looks up MX records for the given domain(s). Note: This command will count towards the DNS API request quota, so it is not recommended to schedule it with high frequency.

Reader Note

Providing an invalid domain input will result in a successful response with no results.

Input

Input Parameter	Required/Optional	Description	Example
Domains	Required	The domains to look up MX records.	["example.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "mx",
        "IsTransitioned": false,
        "CommandArgument": "google.com",
        "TimeRecorded": "2022-01-05T14:09:19.5007286-06:00",
        "ReportingNameServer": "ns4.google.com",
        "TimeToComplete": "57",
        "RelatedIP": null,
        "ResourceRecordType": 15,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "DMARC Record Published",
                "Info": "DMARC Record found",
                "Url": "https://mxtoolbox.com/Problem/mx/DMARC-Record-Published?page=prob_mx&showlogin=1&hidetoc=1&action=mx:google.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            },
            {
                "ID": ******,
                "Name": "DMARC Policy Not Enabled",
                "Info": "DMARC Quarantine/Reject policy enabled",
                "Url": "https://mxtoolbox.com/Problem/mx/DMARC-Policy-Not-Enabled?page=prob_mx&showlogin=1&hidetoc=1&action=mx:google.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            },
            {
                "ID": ****,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/mx/DNS-Record-Published?page=prob_mx&showlogin=1&hidetoc=1&action=mx:google.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Pref": "10",
                "Hostname": "aspmx.l.google.com",
                "IP Address": "1.1.1.1",
                "TTL": "10 min",
                "Asn": "[{\"asname\":\"Google LLC\", \"asn\":\"15169\"}]",
                "IsIpV6": "False"
            },
            {
                "Pref": "10",
                "Hostname": "aspmx.l.google.com",
                "IP Address": "0000:f0b0:000d:c00::0a",
                "TTL": "10 min",
                "Asn": "[]",
                "IsIpV6": "True"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - mx:google.com\r\n\r\n  1 d.gtld-servers.net 1.2.3.4 NON-AUTH 3 ms Received 4 Referrals , rcode=NO_ERROR   google.com.\****\tIN\tNS\tns2.google.com,google.com.\*****\tIN\tNS\tns1.google.com,google.com.\*****\tIN\tNS\tns3.google.com,google.com.\*****\tIN\tNS\tns4.google.com,\r\n  2 ns4.google.com 2.2.2.2 AUTH 2 ms Received 5 Answers , rcode=NO_ERROR   google.com.\*****\tIN\tMX\t20 alt1.aspmx.l.google.com,google.com.\*****\*****\*****\t40 alt3.aspmx.l.google.com,google.com.\****\***\****\t30 alt2.aspmx.l.google.com,google.com.\****\****\*****\t50 alt4.aspmx.l.google.com,google.com.\*****\*****\*****\*****aspmx.l.google.com,\r\nLookupServer 57ms\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": "Google Apps",
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/google.com",
                "Command": "a",
                "CommandArgument": "google.com"
            },
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/google.com",
                "Command": "dns",
                "CommandArgument": "google.com"
            },
            {
                "Name": "spf lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/spf/google.com",
                "Command": "spf",
                "CommandArgument": "google.com"
            },
            {
                "Name": "dns propagation",
                "URL": "https://mxtoolbox.com/api/v1/lookup/mx/google.com:all",
                "Command": "mx",
                "CommandArgument": "google.com:all"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DMARC Record Published\\\",\\\"DMARC Policy Not Enabled\\\",\\\"DNS Record Published\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

PREF	HOSTNAME	IP ADDRESS	TTL	ASN	ISIPV6
10	aspmx.l.google.com	1.1.1.1	10 min	[{"asname":"Google LLC", "asn":"*****"}]	False
10	aspmx.l.google.com	0000:f0b0:000d:c00::0a	10 min	[]	True

Error Handling

If the Return Data is Partially Successful or 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.	Lookup MX Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup MX Record failed.

Status Code: 400.

Message: Name or service not known.

Lookup PTR Record

Looks up DNS pointer records (PTRs) for the given host names. Note: This command will count towards the DNS API request quota, so it is not recommended to schedule it with high frequency.

Input

Input Parameter	Required/Optional	Description	Example
Host Names	Required	The host names to look up PTR records.	["2.2.2.2"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "ipv4",
        "Command": "ptr",
        "IsTransitioned": false,
        "CommandArgument": "8.8.8.8",
        "TimeRecorded": "2022-01-05T14:12:19.6882378-06:00",
        "ReportingNameServer": "ns3.google.com",
        "TimeToComplete": "485",
        "RelatedIP": "8.8.8.8",
        "ResourceRecordType": 12,
        "IsEmptySubDomain": false,
        "IsEndpoint": true,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/ptr/DNS-Record-Published?page=prob_ptr&showlogin=1&hidetoc=1&action=ptr:8.8.8.8",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Type": "PTR",
                "IP Address": "8.8.8.8",
                "Domain Name": "dns.google",
                "TTL": "24 hrs",
                "Asn": "[{\"asname\":\"Google LLC\", \"asn\":\"*****\"},{\"asname\":\"Level 3 Parent, LLC\", \"asn\":\"3356\"}]",
                "IsIpV6": "False"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - ptr:8.8.8.8.in-addr.arpa\r\n\r\n  1 c.in-addr-servers.arpa 1.1.1.1 NON-AUTH 252 ms Received 6 Referrals , rcode=NO_ERROR   8.in-addr.arpa.\t86400\tIN\tNS\tr.arin.net,8.in-addr.arpa.\*****\****\*****\tu.arin.net,8.in-addr.arpa.\****\****\****\tx.arin.net,8.in-addr.arpa.\****\*****\****\ty.arin.net,8.in-addr.arpa.****\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "smtp diag",
                "URL": "https://mxtoolbox.com/api/v1/lookup/smtp/8.8.8.8",
                "Command": "smtp",
                "CommandArgument": "8.8.8.8"
            },
            {
                "Name": "blacklist",
                "URL": "https://mxtoolbox.com/api/v1/lookup/blacklist/8.8.8.8",
                "Command": "blacklist",
                "CommandArgument": "8.8.8.8"
            },
            {
                "Name": "http test",
                "URL": "https://mxtoolbox.com/api/v1/lookup/http/8.8.8.8",
                "Command": "http",
                "CommandArgument": "8.8.8.8"
            },
            {
                "Name": "dns propagation",
                "URL": "https://mxtoolbox.com/api/v1/lookup/ptr/8.8.8.8:all",
                "Command": "ptr",
                "CommandArgument": "8.8.8.8:all"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"ipv4\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DNS Record Published\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

TYPE	IP ADDRESS	DOMAIN NAME	TTL	ASN	ISIPV6
PTR	8.8.8.8	dns.google	24 hrs	[{"asname":"Google LLC", "asn":"***"},{"asname":"Level 3 Parent, LLC", "asn":"***"}]	False

Error Handling

If the Return Data is Partially Successful or 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.	Lookup PTR Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Input. ptr requires a IP Address and hh is a Fully Qualified Domain Name.. Documentation available at https://mxtoolbox.com/restapi.aspx.

Error Sample Data

Lookup PTR Record failed.

Status Code: 400.

Message: Invalid Input. ptr requires a IP Address and hh is a Fully Qualified Domain Name.. Documentation available at https://mxtoolbox.com/restapi.aspx.

Lookup SOA Record

Looks up start of authority (SOA) records for the given domains.

Reader Note

Providing an invalid domain input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

Domains

Required

The domains to look up SOA records.

[

"example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "soa",
        "IsTransitioned": false,
        "CommandArgument": "example.com",
        "TimeRecorded": "2022-01-05T14:21:55.4652082-06:00",
        "ReportingNameServer": "b.iana-*****.net",
        "TimeToComplete": "100",
        "RelatedIP": null,
        "ResourceRecordType": 6,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/soa/DNS-Record-Published?page=prob_soa&showlogin=1&hidetoc=1&action=soa:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Type": "SOA",
                "Domain Name": "example.com",
                "Primary NS": "ns.****.org",
                "Responsible Email": "test@example.icann.org",
                "TTL": "60 min"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - soa:example.com\r\n\r\n  1 m.gtld-servers.net 1.1.1.1NON-AUTH 15 ms Received 2 Referrals , rcode=NO_ERROR   example.com.*****\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/example.com",
                "Command": "a",
                "CommandArgument": "example.com"
            },
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/example.com",
                "Command": "dns",
                "CommandArgument": "example.com"
            },
            {
                "Name": "mx lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/mx/example.com",
                "Command": "mx",
                "CommandArgument": "example.com"
            },
            {
                "Name": "spf lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/spf/example.com",
                "Command": "spf",
                "CommandArgument": "example.com"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

TYPE	DOMAIN NAME	PRIMARY NS	RESPONSIBLE EMAIL	TTL
SOA	example.com	ns.icann.org	example@user.icann.org	60 min

Error Handling

If the Return Data is Partially Successful or 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.	Lookup SOA Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup SOA Record failed.

Status Code: 400.

Message: Name or service not known.

Lookup SPF Record

Looks up sender policy framework (SPF) records for the given domains.

Reader Note

Providing an invalid domain input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

Domains

Required

The domains to look up SPF records.

[

"example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "spf",
        "IsTransitioned": false,
        "CommandArgument": "example.com",
        "TimeRecorded": "2022-01-05T14:11:14.6152337-06:00",
        "ReportingNameServer": "b.iana-*****.net",
        "TimeToComplete": "73",
        "RelatedIP": null,
        "ResourceRecordType": 16,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "SPF Record Published",
                "Info": "SPF Record found",
                "Url": "https://mxtoolbox.com/Problem/spf/SPF-Record-Published?page=prob_spf&showlogin=1&hidetoc=1&action=spf:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            },
            {
                "ID": *****,
                "Name": "SPF Record Deprecated",
                "Info": "No deprecated records found",
                "Url": "https://mxtoolbox.com/Problem/spf/SPF-Record-Deprecated?page=prob_spf&showlogin=1&hidetoc=1&action=spf:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Prefix": "",
                "Type": "record",
                "Value": "txt",
                "PrefixDesc": "",
                "Description": "v=spf1 -all",
                "RecordNum": "1"
            },
            {
                "Prefix": "",
                "Type": "v",
                "Value": "spf1",
                "PrefixDesc": "",
                "Description": "The SPF record version",
                "RecordNum": null
            },
            {
                "Prefix": "-",
                "Type": "all",
                "Value": "",
                "PrefixDesc": "Fail",
                "Description": "Always matches. It goes at the end of your record.",
                "RecordNum": null
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - txt:example.com\r\n\r\n  1 k.gtld-servers.net 1.1.1.1 NON-AUTH 25 ms Received 2 Referrals , rcode=NO_ERROR   example.com.*****\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/example.com",
                "Command": "a",
                "CommandArgument": "example.com"
            },
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/example.com",
                "Command": "dns",
                "CommandArgument": "example.com"
            },
            {
                "Name": "mx lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/mx/example.com",
                "Command": "mx",
                "CommandArgument": "example.com"
            },
            {
                "Name": "dns propagation",
                "URL": "https://mxtoolbox.com/api/v1/lookup/spf/example.com:all",
                "Command": "spf",
                "CommandArgument": "example.com:all"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"SPF Record Published\\\",\\\"SPF Record Deprecated\\\",\\\"SPF Multiple Records\\\",\\\"SPF Contains characters after ALL\\\",\\\"SPF Syntax Check\\\",\\\"SPF Included Lookups\\\",\\\"SPF Type PTR Check\\\",\\\"SPF Void Lookups\\\",\\\"SPF MX Resource Records\\\",\\\"SPF Record Null Value\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

PREFIX	TYPE	VALUE	PREFIXDESC	DESCRIPTION	RECORDNUM
	record	txt		v=spf1 -all	1
	v	spf1		The SPF record version	None
-	all		Fail	Always matches. It goes at the end of your record.	None

Error Handling

If the Return Data is Partially Successful or 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.	Lookup SPF Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup SPF Record failed.

Status Code: 400.

Message: Name or service not known.

Lookup TXT Record

Looks up DNS text (TXT) records for the given domains.

Reader Note

Providing an invalid domain input will result in a successful response with no results.

Input

Input Parameter

Required/Optional

Description

Example

Domains

Required

The domains to look up TXT records.

[

"example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "UID": null,
        "ArgumentType": "domain",
        "Command": "txt",
        "IsTransitioned": false,
        "CommandArgument": "example.com",
        "TimeRecorded": "2022-01-05T14:15:39.9539733-06:00",
        "ReportingNameServer": "b.iana-servers.net",
        "TimeToComplete": "60",
        "RelatedIP": null,
        "ResourceRecordType": 16,
        "IsEmptySubDomain": false,
        "IsEndpoint": false,
        "HasSubscriptions": false,
        "AlertgroupSubscriptionId": null,
        "Failed": [],
        "Warnings": [],
        "Passed": [
            {
                "ID": *****,
                "Name": "DNS Record Published",
                "Info": "DNS Record found",
                "Url": "https://mxtoolbox.com/Problem/txt/DNS-Record-Published?page=prob_txt&showlogin=1&hidetoc=1&action=txt:example.com",
                "PublicDescription": null,
                "IsExcludedByUser": false
            }
        ],
        "Timeouts": [],
        "Errors": [],
        "IsError": false,
        "Information": [
            {
                "Type": "TXT",
                "Domain Name": "example.com",
                "TTL": "24 hrs",
                "Record": "v=*****-all"
            },
            {
                "Type": "TXT",
                "Domain Name": "example.com",
                "TTL": "24 hrs",
                "Record": "*****"
            }
        ],
        "MultiInformation": [],
        "Transcript": [
            {
                "Transcript": "- - - txt:example.com\r\n\r\n  1 h.gtld-servers.net 1.1.1.1 NON-AUTH 34 ms Received 2 Referrals , rcode=NO_ERROR   example.com.*****\r\n"
            }
        ],
        "MxRep": 0,
        "EmailServiceProvider": null,
        "DnsServiceProvider": null,
        "DnsServiceProviderIdentifier": null,
        "RelatedLookups": [
            {
                "Name": "dns lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/a/example.com",
                "Command": "a",
                "CommandArgument": "example.com"
            },
            {
                "Name": "dns check",
                "URL": "https://mxtoolbox.com/api/v1/lookup/dns/example.com",
                "Command": "dns",
                "CommandArgument": "example.com"
            },
            {
                "Name": "mx lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/mx/example.com",
                "Command": "mx",
                "CommandArgument": "example.com"
            },
            {
                "Name": "spf lookup",
                "URL": "https://mxtoolbox.com/api/v1/lookup/spf/example.com",
                "Command": "spf",
                "CommandArgument": "example.com"
            },
            {
                "Name": "dns propagation",
                "URL": "https://mxtoolbox.com/api/v1/lookup/txt/example.com:all",
                "Command": "txt",
                "CommandArgument": "example.com:all"
            }
        ]
    }
]

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

CODE

{
    "ArgumentTypes": "\"[\\\"domain\\\"]\"",
    "RecordCategoryIDs": "\"[*****]\"",
    "RecordCategoryNames": "\"[\\\"DNS Record Published\\\"]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Result

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

SAMPLE DATA

TYPE	DOMAIN NAME	TTL	RECORD
TXT	example.com	24 hrs	v=*****-all
TXT	example.com	24 hrs	yx*****l2

Error Handling

If the Return Data is Partially Successful or 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.	Lookup TXT Record 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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Lookup TXT Record failed.

Status Code: 400.

Message: Name or service not known.

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.

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 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.	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 MXToolBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Name or service not known.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Name or service not known.