Cisco Umbrella Enforcement

LAST UPDATED: NOVEMBER 10, 2025

Overview

Cisco Umbrella is cloud-delivered enterprise network security which provides users with a first line of defense against cybersecurity threats. Integration with Cisco Umbrella can help users to collect, research, and visualize security event data and also enables users to programmatically check the state of domains. For each domain evaluated, Umbrella either blocks or allows the domain.

D3 SOAR is providing REST operations to function with Cisco Umbrella Enforcement.

Cisco Umbrella Enforcement is available for use in:

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

Known Limitations

For more information about the rate limits of the Umbrella API, see Umbrella API Rate Limits - Cisco Developer.

Connection

To connect to Cisco Umbrella Enforcement from D3 SOAR, follow this part to collect the required information below:

Parameter	Description	Example
Investigate Token	The authentication token for the Investigate API.	*----**
Enforcement Token	The authentication token for the Enforcement API.	*----**
Management Key	The authentication token for the Management API.	***
Management Secret	The authentication secret for the Investigate API.	***
Organization ID	The organization ID for the Management API.	***

Permission Requirements

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

Command	Required Permission
Add Destinations To Destination List	Full Admin
Add Domains To Domain List	Full Admin
Delete Enforced Domains	Full Admin
Get ASN For IPs	Investigate Only
Get Destinations By Destination List	Full Admin
Get Domain Status	Investigate Only
Get Geo Info For ASNs	Investigate Only
Get Latest Malicious Domain	Investigate Only
Get Related Domains	Investigate Only
Get Risk Score Of Domains	Investigate Only
Get Security Info Of Domains	Investigate Only
List Enforced Domains	Full Admin
Register Enforced Domains	Full Admin
Remove Destinations From Destination List	Full Admin
Who Is Domains	Investigate Only
Who Is Emails	Investigate Only
Test Connection	Full Admin

READER NOTE

Only the Full Admin role can create Enforcement Tokens, Management Keys, and Secrets. Commands requiring the Investigate Only role can run with an Investigate Token. When only an Investigate Token is provided, connection tests may fail; however, the commands will still run successfully through the saved connection.

Configuring Cisco Umbrella Enforcement to Work with D3 SOAR

Log in to the Cisco Umbrella Portal.

Creating Users and Assigning Roles

READER NOTE

This section is intended for administrators to create new user accounts.

Navigate to Admin > Accounts, then click + New button in the top right corner of the screen to create a new user.
Enter the user's email address and select the appropriate user role from the dropdown menu.
Click SEND INVITATION to invite the user.
Instruct the user to check for the activation email and follow its instructions. The account status displays Pending until activation is complete.

Creating Investigate API Tokens

Navigate to Investigate > API Keys.
Click the + CREATE NEW TOKEN button, enter a title, then click the CREATE button.
Copy and save the access token. This token will be used as the Investigate Token when setting up the integration connection in D3 SOAR.

Creating Enforcement Tokens

Navigate to Policies > Policy Components > Integration Settings, then click the + Add button to create a new integration.
Enter the integration name and click the CREATE button.
Open the newly created integration and enable the Integration Enabled option, then copy and save the customerKey (the string value following "customerKey=" in the Integration URL). This will be used as the Enforcement Token when setting up the integration connection in D3 SOAR.

Creating Management Keys and Secrets

Navigate to Admin > API Keys, then click the Legacy Keys card and select Umbrella Management.
Click the REFRESH button, then copy and save the key and secret values. These will be used when setting up the integration connection in D3 SOAR.

Obtaining the Organization ID

After signing in to the Cisco Umbrella Enforcement portal, locate the Organization ID in the URL https://dashboard.umbrella.com/o/<OrgID>/#/<page>, where <OrgID> is the organization’s unique identifier.

Configuring D3 SOAR to Work with Cisco Umbrella Enforcement

Log in to D3 SOAR.
Find the Cisco Umbrella Enforcement integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Cisco Umbrella Enforcement in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Cisco Umbrella Enforcement.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all 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 is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): 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): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users 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: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Copy the Investigate Token from the Cisco Umbrella Enforcement platform. Refer to Creating Investigate API Tokens for details.
  2. Copy the Enforcement Token from the Cisco Umbrella Enforcement platform. Refer to Creating Enforcement Tokens for details.
  3. Copy the Management Key from the Cisco Umbrella Enforcement platform. Refer to Creating Management Keys and Secrets for details.
  4. Copy the Management Secret Token from the Cisco Umbrella Enforcement platform. Refer to Creating Management Keys and Secrets for details.
  5. Copy the Organization ID from the Cisco Umbrella Enforcement platform. Refer to Obtaining the Organization ID for details.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Cisco Umbrella Enforcement includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Cisco Umbrella Enforcement API, refer to the Cisco Umbrella Enforcement API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Cisco Umbrella Enforcement to Work with D3 SOAR for details.

Add Destinations To Destination List

Adds specified destinations to the destination list.

Input

Input Parameter	Required/Optional	Description	Example
Destinations	Required	The list of destinations to add to the destination list. Destinations can be specified as IP addresses, domains, or URLs.	JSON `[ "9.9.9.20", "9.9.9.21" ]`
Destination List Name	Required	The name of the destination list to add the specified destinations.	Global Allow List
Comment	Optional	A comment to accompany the additions to the destination list.	test domain, twitter21.com

Output

To view the sample output data for all commands, refer to this article.

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 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.	Add Destinations To Destination 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 Cisco Umbrella Enforcement 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 Destination.

Error Sample Data

Add Destinations To Destination List failed.

Status Code: 401.

Message: Invalid Destination.

Add Domains To Domain List

Posts malware events in the Umbrella Generic Event Format for further processing with the option to add these events to a customer's domain lists. The command will then return the current domain list.

Input

Input Parameter

Required/Optional

Description

Example

customerKey

Optional

The customerKey, which is the same as the enforcement token used to configure the integration connection. Please note that the customerKey or enforcement token entered here will not affect the configuration of the underlying integration connection.

***-***-***-***-***

events

Optional

The JSON object containing the list of malware events and domains to add to the domain list.

JSON

[
  {
    "alertTime": "2021-07-08T11:14:26Z",
    "deviceId": "***-***-***-***-***",
    "deviceVersion": "13.7a",
    "dstDomain": "domain",
    "dstUrl": "http://xmr.pool.minergate.com",
    "eventTime": "2021-02-08T09:30:26Z",
    "protocolVersion": "1.0b",
    "providerName": "Security Platform"
  },
  {
    "alertTime": "2021-07-08T11:14:26Z",
    "deviceId": "***-***-***-***-***",
    "deviceVersion": "13.7a",
    "dstDomain": "domain",
    "dstUrl": "http://xmr.pool.minergate.com",
    "eventTime": "2021-02-08T09:30:26Z",
    "protocolVersion": "1.0b",
    "providerName": "Security Platform"
  }
]

Output

To view the sample output data for all commands, refer to this article.

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 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.	Add Domains To Domain 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: customKey Not Found.

Error Sample Data

Add Domains To Domain List failed.

Status Code: 404.

Message: customKey Not Found.

Delete Enforced Domains

Deletes the specified enforced domains.

Input

Input Parameter	Required/Optional	Description	Example
Domains	Required	The list of enforced domains to delete.	JSON `[ "domain1", "domain2" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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.	Delete Enforced Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Delete Enforced Domains failed.

Status Code: 401.

Message: Invalid Domain.

Get ASN For IPs

Retrieves Autonomous System Numbers (ASN) and relevant information on the specified IP addresses.

Input

Input Parameter	Required/Optional	Description	Example
ips	Required	The list of IP addresses to query	JSON `[ "8.8.8.8" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 ASN For IPs 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 Cisco Umbrella Enforcement 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 ip.

Error Sample Data

Get ASN For IPs failed.

Status Code: 401.

Message: invalid ip.

Get Destinations By Destination List

Retrieves destinations from the specified destination list.

Input

Input Parameter	Required/Optional	Description	Example
Destination List Name	Required	The name of the destination list to retrieve destinations.	Global Allow List

Output

To view the sample output data for all commands, refer to this article.

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 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 Destinations By Destination 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Destination List Name Not Found.

Error Sample Data

Get Destinations By Destination List failed.

Status Code: 404.

Message: Destination List Name Not Found.

Get Domain Status

Returns the status of the specified domains.

Input

Input Parameter	Required/Optional	Description	Example
domains	Optional	The list of domains to query.	JSON `[ "google.com" ]`
tierLevel	Optional	The level of access granted to the API. Tier 0 and Tier 1 do not support bulk requests, while Tier 2 and Tier 3 allow the use of bulk requests.	0
showLable	Optional	The option to return content categories by their names, when set to True. Setting this parameter to False will return category IDs instead.	True

Output

To view the sample output data for all commands, refer to this article.

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 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 Domain Status 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 Cisco Umbrella Enforcement 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 domain name.

Error Sample Data

Get Domain Status failed.

Status Code: 401.

Message: Invalid domain name.

Get Geo Info For ASNs

Retrieves prefix routing information on the specified Autonomous System Numbers (ASNs).

Input

Input Parameter	Required/Optional	Description	Example
asns	Optional	The list of ASNs to query.	JSON `[ "***" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 Geo Info For ASNs 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: asns not found.

Error Sample Data

Get Geo Info For ASNs failed.

Status Code: 404.

Message: asns not found.

Get Latest Malicious Domain

Retrieves any known malicious domains associated with the specified IP addresses. If no malicious domains are known, the result will be empty.

Input

Input Parameter	Required/Optional	Description	Example
ips	Optional	The list of IP addresses to query.	JSON `[ "1.1.1.1" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 Latest Malicious Domain 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 Cisco Umbrella Enforcement 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 ip.

Error Sample Data

Get Latest Malicious Domain failed.

Status Code: 401.

Message: Invalid ip.

Get Related Domains

Retrieves a list of domain names that have been commonly requested around the same time as the specified domain names.

Input

Input Parameter	Required/Optional	Description	Example
domains	Optional	The list of domains to query.	JSON `[ "amazon.com" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 Related Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Get Related Domains failed.

Status Code: 401.

Message: Invalid Domain.

Get Risk Score Of Domains

Retrieves Umbrella Investigate Risk Scores for the specified domains. The risk score is measured on a scale from 0 to 100, where a higher score indicates a greater level of risk, while a score of 0 represents no risk at all.

Input

Input Parameter	Required/Optional	Description	Example
domains	Optional	The list of domains to query.	JSON `[ "amazon.com" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 Risk Score Of Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Get Risk Score Of Domains failed.

Status Code: 401.

Message: Invalid Domain.

Get Security Info Of Domains

Retrieves multiple scores and security features related to the specified domains, which can be used to determine relevant datapoints to build insight on the reputation or security risk posed by the site.

Input

Input Parameter	Required/Optional	Description	Example
domains	Optional	The list of domains to query.	JSON `[ "amazon.com" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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 Security Info Of Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Get Security Info Of Domains failed.

Status Code: 401.

Message: Invalid Domain.

List Enforced Domains

Retrieves a list of enforced domains.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

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 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.	List Enforced Domains 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Forbidden Testing enforcement token fail. Message Invalid credentials supplied (Event failed to be recorded) Testing management token fail. Message Invalid authentication credentials.

Error Sample Data

List Enforced Domains failed.

Status Code: 403.

Message: Forbidden

Testing enforcement token fail. Message Invalid credentials supplied (Event failed to be recorded)

Testing management token fail. Message Invalid authentication credentials.

Register Enforced Domains

Registers a list of domains under umbrella enforcement with the option to include the specified domains in the domain list.

Input

Input Parameter	Required/Optional	Description	Example
Domains	Required	The list of domains to register.	JSON `[ "*", "*" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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.	Register Enforced Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Register Enforced Domains failed.

Status Code: 401.

Message: Invalid Domain.

Remove Destinations From Destination List

Removes specified destinations from the destination list.

Input

Input Parameter	Required/Optional	Description	Example
Destination List Name	Required	The name of the destination list to remove destinations.	Global Allow List
Destinations	Required	The destinations to remove from the destination list.	JSON `[ "9.9.9.10", "9.9.9.11" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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.	Remove Destinations From Destination 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Destination List Name Not Found.

Error Sample Data

Remove Destinations From Destination List failed.

Status Code: 404.

Message: Destination List Name Not Found.

Who Is Domains

Retrieves standard WHOIS response records for the specified domains, including all the available WHOIS data.

Input

Input Parameter	Required/Optional	Description	Example
domains	Optional	The list of domains to query.	JSON `[ "google.com" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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.	Who Is Domains 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 Cisco Umbrella Enforcement 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 Domain.

Error Sample Data

Who Is Domains failed.

Status Code: 401.

Message: Invalid Domain.

Who Is Emails

Retrieves domain addresses in the registrar associated with the specified email addresses.

Input

Input Parameter	Required/Optional	Description	Example
emails	Optional	The list of email addresses to query.	JSON `[ "test@example.com" ]`

Output

To view the sample output data for all commands, refer to this article.

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 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.	Who Is Emails 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 Cisco Umbrella Enforcement 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 Email.

Error Sample Data

Who Is Emails failed.

Status Code: 401.

Message: Invalid Email.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

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

More details about an error can be viewed in the Error tab.

String

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 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 Cisco Umbrella Enforcement portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Forbidden Testing enforcement token fail. Message Invalid credentials supplied (Event failed to be recorded) Testing management token fail. Message Invalid authentication credentials.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Forbidden

Testing enforcement token fail. Message Invalid credentials supplied (Event failed to be recorded)

Testing management token fail. Message Invalid authentication credentials.