Skip to main content
Skip table of contents

Cisco Umbrella Enforcement

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, please 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

Please note that only Full Admin can be used to create Enforcement tokens, Management Keys and Secrets. For those commands that need an Investigate Only role, an Investigate Token is enough to run. If you just provide the Investigate token (leave other parameters empty), you will see errors when test connection, just save the connection and use that connection to test commands, those commands can still run without passed connections, no matter the connection passed or not.

Configuring Cisco Umbrella Enforcement to Work with D3 SOAR

Log in to the Cisco Umbrella Portal (https://dashboard.umbrella.com/) with your credentials.

Creating Users and Assigning Roles

  1. From the left sidebar menu, select Accounts under Admin. Click on + New located at the top right of the screen to create a new user.

  2. Enter the user's email address and select the appropriate user role from the dropdown menu.

  3. Click on SEND INVITATION to invite the user. An email will be sent to the provided email address. Check the user's email account and follow the instructions to activate the account. The account status will be shown as pending until activation is complete.

  4. Provide the required information to complete the account creation process.

  5. Log out of your current account and log in using the newly created account.

  6. Refer to the sections below to generate tokens. Tokens will inherit permissions from the corresponding account they were generated from.

Creating Investigate API Tokens

  1. From the left sidebar menu, select API Keys under Investigate.

  2. Click on + CREATE NEW TOKEN located on the top right corner. Enter a title for the token and click CREATE.

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

  1. From the left sidebar menu, navigate to Policies > Policy Components > Integration Settings. Click + Add at the top right corner to create a new integration.

  2. Enter the Integration Name and click CREATE.

  3. Open the newly created integration and toggle the Integration Enabled switch to enable it. Copy and save the customerKey. The customerKey is 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. Click SAVE.

Creating Management Keys and Secrets

  1. From the left sidebar menu, select API Keys under Admin. Click on Legacy Keys at the top right corner and select Umbrella Management.

  2. Click on REFRESH, then copy and save the key and secret values provided. These will be used when setting up the integration connection in D3 SOAR.

Obtaining the Organization ID

Once logged into the Cisco Umbrella Enforcement portal, you can find the Organization ID in the URL. The Organization ID is located at https://dashboard.umbrella.com/o/<OrgID>/#/<page>, where <OrgID> represents your Organization ID.

Configuring D3 SOAR to Work with Cisco Umbrella Enforcement

  1. Log in to D3 SOAR.

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

  3. Configure the following fields to create a connection to Cisco Umbrella Enforcement.

    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. Configure User Permissions: Defines which users have access to the connection.

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

    8. 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 more details.
      2. Copy the Enforcement Token from the Cisco Umbrella Enforcement platform. Refer to Creating Enforcement Tokens for more details.
      3. Copy the Management Key from the Cisco Umbrella Enforcement platform. Refer to Creating Management Keys and Secrets for more details.
      4. Copy the Management Secret Token from the Cisco Umbrella Enforcement platform. Refer to Creating Management Keys and Secrets for more details.
      5. Copy the Organization ID from the Cisco Umbrella Enforcement platform. Refer to Obtaining the Organization ID for more details.

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

    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.

  4. Test the connection.

    1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

    2. Click OK to close the alert window.

    3. Click + Add to create and add the configured connection.

Commands

Cisco Umbrella Enforcement 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 Cisco Umbrella Enforcement API, please refer to the Cisco Umbrella Enforcement API reference.

Reader Note

Certain permissions are required for each command. Please 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.

["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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "status": {
        "code": 200,
        "text": "OK"
    },
    "data": {
        "id": ***,
        "organizationId": ***,
        "access": "allow",
        "isGlobal": true,
        "name": "Global Allow List",
        "thirdpartyCategoryId": null,
        "createdAt": "2021-07-26T10:02:13-07:00",
        "modifiedAt": "2021-08-05T15:39:04-07:00",
        "isMspDefault": false,
        "markedForDeletion": false,
        "bundleTypeId": 1,
        "meta": {
            "destinationCount": 11
        }
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.data in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "id": ***,
    "organizationId": ***,
    "access": "allow",
    "isGlobal": true,
    "name": "Global Allow List",
    "thirdpartyCategoryId": null,
    "createdAt": "2021-07-26T10:02:13-07:00",
    "modifiedAt": "2021-08-05T15:39:04-07:00",
    "isMspDefault": false,
    "markedForDeletion": false,
    "bundleTypeId": 1,
    "meta": {
        "destinationCount": 11
    }
}
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

id

***

organizationId

***

access

allow

isGlobal

True

name

Global Allow List

thirdpartyCategoryId

createdAt

7/26/2021 10:02:13 AM

modifiedAt

8/5/2021 3:39:04 PM

isMspDefault

False

markedForDeletion

False

bundleTypeId

1

meta

{

"destinationCount": 11

}

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.

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.

[

{

"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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "id": "***,***,***,***",
    "meta": {
        "page": 1,
        "limit": 200,
        "prev": false,
        "next": false
    },
    "data": [
        {
            "id": ***,
            "name": "xmr.pool.minergate.com",
            "lastSeenAt": 1627688341
        },
        {
            "id": ***,
            "name": "evilactor.com",
            "lastSeenAt": 1627520863
        },
        {
            "id": ***,
            "name": "evilactor123.com",
            "lastSeenAt": 1627530853
        },
        {
            "id": ***,
            "name": "evilactor456.com",
            "lastSeenAt": 1627577025
        },
        {
            "id": ***,
            "name": "xmr2.pool.minergate.com",
            "lastSeenAt": 1627688661
        },
        {
            "id": ***,
            "name": "xmr30.pool.minergate.com",
            "lastSeenAt": 1629999768
        },
        {
            "id": ***,
            "name": "xmr31.pool.minergate.com",
            "lastSeenAt": 1629999768
        },
        {
            "id": ***,
            "name": "www.ibm3.com",
            "lastSeenAt": 1629926060
        },
        {
            "id": ***,
            "name": "www.ibm2.com",
            "lastSeenAt": 1629926059
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "id": "***,***,***,***",
    "meta": {
        "page": 1,
        "limit": 200,
        "prev": false,
        "next": false
    },
    "data": [
        {
            "id": ***,
            "name": "xmr.pool.minergate.com",
            "lastSeenAt": 1627688341
        },
        {
            "id": ***,
            "name": "evilactor.com",
            "lastSeenAt": 1627520863
        },
        {
            "id": ***,
            "name": "evilactor123.com",
            "lastSeenAt": 1627530853
        },
        {
            "id": ***,
            "name": "evilactor456.com",
            "lastSeenAt": 1627577025
        },
        {
            "id": ***,
            "name": "xmr2.pool.minergate.com",
            "lastSeenAt": 1627688661
        },
        {
            "id": ***,
            "name": "xmr30.pool.minergate.com",
            "lastSeenAt": 1629999768
        },
        {
            "id": ***,
            "name": "xmr31.pool.minergate.com",
            "lastSeenAt": 1629999768
        },
        {
            "id": ***,
            "name": "www.ibm3.com",
            "lastSeenAt": 1629926060
        },
        {
            "id": ***,
            "name": "www.ibm2.com",
            "lastSeenAt": 1629926059
        }
    ]
}
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

id

***,***,***,***

meta

{

"page": 1,

"limit": 200,

"prev": false,

"next": false

}

data

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.

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.

["domain1","domain2"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "domain": "domain1",
        "actionResult": "Deleted domain successfully"
    },
    {
        "domain": "domain2",
        "actionResult": "Deleted domain successfully"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "domain": "domain1",
        "actionResult": "Deleted domain successfully"
    },
    {
        "domain": "domain2",
        "actionResult": "Deleted domain successfully"
    }
]
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

DOMAIN

ACTIONRESULT

domain1

Deleted domain successfully

xdomain2

Deleted domain successfully

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.

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

["8.8.8.8"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "ip": "8.8.8.8",
        "asn": [
            {
                "cidr": "8.0.0.0/12",
                "asn": ***,
                "ir": 3,
                "description": "LEVEL3, US ***",
                "creation_date": "2000-03-10",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            },
            {
                "cidr": "8.0.0.0/9",
                "asn": ***,
                "ir": 3,
                "description": "LEVEL3, US ***",
                "creation_date": "2000-03-10",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            },
            {
                "cidr": "8.8.8.0/24",
                "asn": ***,
                "ir": 3,
                "description": "GOOGLE, US ***",
                "creation_date": "2000-03-30",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            }
        ]
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "ip": "8.8.8.8",
        "asn": [
            {
                "cidr": "8.0.0.0/12",
                "asn": ***,
                "ir": 3,
                "description": "LEVEL3, US ***",
                "creation_date": "2000-03-10",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            },
            {
                "cidr": "8.0.0.0/9",
                "asn": ***,
                "ir": 3,
                "description": "LEVEL3, US ***",
                "creation_date": "2000-03-10",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            },
            {
                "cidr": "8.8.8.0/24",
                "asn": ***,
                "ir": 3,
                "description": "GOOGLE, US ***",
                "creation_date": "2000-03-30",
                "RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
            }
        ]
    }
]
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

IP

ASN

8.8.8.8

[
{
"cidr": "8.0.0.0/12",
"asn": ***,
"ir": 3,
"description": "LEVEL3, US ***",
"creation_date": "2000-03-10",
"RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
},
{
"cidr": "8.0.0.0/9",
"asn": ***,
"ir": 3,
"description": "LEVEL3, US ***",
"creation_date": "2000-03-10",
"RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
},
{
"cidr": "8.8.8.0/24",
"asn": ***,
"ir": 3,
"description": "GOOGLE, US ***",
"creation_date": "2000-03-30",
"RegistryRegion": "ARIN: United States, Canada, several parts of the Caribbean region, and Antarctica."
}
]

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "status": {
        "code": 200,
        "text": "OK"
    },
    "meta": {
        "page": 1,
        "limit": 100,
        "total": 9
    },
    "data": [
        {
            "id": "***",
            "destination": "9.9.9.9",
            "type": "ipv4",
            "comment": null,
            "createdAt": "2021-08-03 18:36:11"
        },
        {
            "id": "***",
            "destination": "9.9.9.10",
            "type": "ipv4",
            "comment": null,
            "createdAt": "2021-08-05 22:05:13"
        },
        {
            "id": "***",
            "destination": "***999.com",
            "type": "domain",
            "comment": "test domain, video games",
            "createdAt": "2021-07-31 01:12:57"
        },
        {
            "id": "***",
            "destination": "***999.com",
            "type": "domain",
            "comment": "test domain, twitter.com",
            "createdAt": "2021-07-31 01:12:57"
        },
        {
            "id": "***",
            "destination": "***888.com",
            "type": "domain",
            "comment": "test domain, video games",
            "createdAt": "2021-07-31 01:05:27"
        },
        {
            "id": "***",
            "destination": "***777.com",
            "type": "domain",
            "comment": "test domain, video games",
            "createdAt": "2021-07-31 01:16:26"
        },
        {
            "id": "***",
            "destination": "9.9.9.11",
            "type": "ipv4",
            "comment": null,
            "createdAt": "2021-08-05 20:56:22"
        },
        {
            "id": "***",
            "destination": "9.9.9.18",
            "type": "ipv4",
            "comment": "test domain, ***19.com",
            "createdAt": "2021-08-05 22:00:32"
        },
        {
            "id": "***",
            "destination": "9.9.9.19",
            "type": "ipv4",
            "comment": "test domain, ***19.com",
            "createdAt": "2021-08-05 22:00:32"
        }
    ]
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.data in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "id": "***",
        "destination": "9.9.9.9",
        "type": "ipv4",
        "comment": null,
        "createdAt": "2021-08-03 18:36:11"
    },
    {
        "id": "***",
        "destination": "9.9.9.10",
        "type": "ipv4",
        "comment": null,
        "createdAt": "2021-08-05 22:05:13"
    },
    {
        "id": "***",
        "destination": "***999.com",
        "type": "domain",
        "comment": "test domain, video games",
        "createdAt": "2021-07-31 01:12:57"
    },
    {
        "id": "***",
        "destination": "***999.com",
        "type": "domain",
        "comment": "test domain, twitter.com",
        "createdAt": "2021-07-31 01:12:57"
    },
    {
        "id": "***",
        "destination": "***888.com",
        "type": "domain",
        "comment": "test domain, video games",
        "createdAt": "2021-07-31 01:05:27"
    },
    {
        "id": "***",
        "destination": "***777.com",
        "type": "domain",
        "comment": "test domain, video games",
        "createdAt": "2021-07-31 01:16:26"
    },
    {
        "id": "***",
        "destination": "9.9.9.11",
        "type": "ipv4",
        "comment": null,
        "createdAt": "2021-08-05 20:56:22"
    },
    {
        "id": "***",
        "destination": "9.9.9.18",
        "type": "ipv4",
        "comment": "test domain, ***19.com",
        "createdAt": "2021-08-05 22:00:32"
    },
    {
        "id": "***",
        "destination": "9.9.9.19",
        "type": "ipv4",
        "comment": "test domain, ***19.com",
        "createdAt": "2021-08-05 22:00:32"
    }
]
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 
{
    "IDs": [
        "***",
        "***",
        "***",
        "***",
        "***",
        "***",
        "***",
        "***",
        "***"
    ],
    "Destinations": [
        "9.9.9.9",
        "9.9.9.10",
        "***999.com",
        "***999.com",
        "***888.com",
        "***777.com",
        "9.9.9.11",
        "9.9.9.18",
        "9.9.9.19"
    ],
    "Types": [
        "ipv4",
        "ipv4",
        "domain",
        "domain",
        "domain",
        "domain",
        "ipv4",
        "ipv4",
        "ipv4"
    ],
    "Comments": [
        "None",
        "None",
        "test domain, video games",
        "test domain, twitter.com",
        "test domain, video games",
        "test domain, video games",
        "None",
        "test domain, twitter19.com",
        "test domain, twitter19.com"
    ],
    "CreatedAts": [
        "2021-08-03 18:36:11",
        "2021-08-05 22:05:13",
        "2021-07-31 01:12:57",
        "2021-07-31 01:12:57",
        "2021-07-31 01:05:27",
        "2021-07-31 01:16:26",
        "2021-08-05 20:56:22",
        "2021-08-05 22:00:32",
        "2021-08-05 22:00:32"
    ]
}
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

ID

DESTINATION

TYPE

COMMENT

CREATEDAT

***

9.9.9.9

ipv4

2021-08-03 18:36:11

***

9.9.9.10

ipv4

2021-08-05 22:05:13

***

***999.com

domain

test domain, video games

2021-07-31 01:12:57

***

***999.com

domain

test domain, twitter.com

2021-07-31 01:12:57

***

***888.com

domain

test domain, video games

2021-07-31 01:05:27

***

***777.com

domain

test domain, video games

2021-07-31 01:16:26

***

9.9.9.11

ipv4

2021-08-05 20:56:22

***

9.9.9.18

ipv4

test domain, ***19.com

2021-08-05 22:00:32

***

9.9.9.19

ipv4

test domain, ***19.com

2021-08-05 22:00:32

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "google.com": {
            "status": 1,
            "security_categories": [],
            "content_categories": [
                "Search Engines"
            ],
            "domain": "google.com",
            "statusName": "benign"
        }
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "status": 1,
        "security_categories": [],
        "content_categories": [
            "Search Engines"
        ],
        "domain": "google.com",
        "statusName": "benign"
    }
]
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

GOOGLE.COM

{
"status": 1,
"security_categories": [],
"content_categories": [
"Search Engines"
],
"domain": "google.com",
"statusName": "benign"
}

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["***"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "asn": "***",
        "prefixRoutingInfo": [
            {
                "cidr": "1.1.1.1/22",
                "geo": {
                    "country_name": "United States",
                    "country_code": "US"
                }
            }
        ]
    }
]
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

ASN

PREFIXROUTINGINFO

***

[
{
"cidr": "1.1.1.1/22",
"geo": {
"country_name": "United States",
"country_code": "US"
}
}
]

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["1.1.1.1"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "ip": "1.1.1.1",
        "MaliciousDomain": [
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            }
        ]
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "ip": "1.1.1.1",
        "MaliciousDomain": [
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            },
            {
                "id": ***,
                "name": "***"
            }
        ]
    }
]
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

IP

MALICIOUSDOMAIN

1.1.1.1

[
{
"id": ***,
"name": "***"
},
{
"id": ***,
"name": "***"
},
{
"id": ***,
"name": "***"
},
{
"id": ***,
"name": "***"
},
{
"id": ***,
"name": "***"
},
{
"id": ***,
"name": "***"
}
]

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["amazon.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "tb1": [
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ]
        ],
        "found": true,
        "domain": "amazon.com"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "domain": "amazon.com",
        "tb1": [
            {
        "tb1": [
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ],
            [
                "***",
                ***
            ]
        ],
        "found": true
    }
]
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

DOMAIN

TB1

FOUND

http://amazon.com

[
{
"domain": "*** ",
"score": ***
},
{
"domain": "*** ",
"score": ***
},
{
"domain": "***",
"score": ***
},
{
"domain": "***",
"score": ***
}
]

True

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["amazon.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "indicators": [
            {
                "indicator": "Geo Popularity Score",
                "normalized_score": 2,
                "score": -3.6108781699999994
            },
            {
                "indicator": "Keyword Score",
                "normalized_score": 5,
                "score": 0.05582814570422924
            },
            {
                "indicator": "Lexical",
                "normalized_score": 71,
                "score": 0.717
            },
            {
                "indicator": "Popularity 1 Day",
                "normalized_score": 100,
                "score": 167.46
            },
            {
                "indicator": "Popularity 30 Day",
                "normalized_score": 100,
                "score": 166.93
            },
            {
                "indicator": "Popularity 7 Day",
                "normalized_score": 100,
                "score": 167.07
            },
            {
                "indicator": "Popularity 90 Day",
                "normalized_score": 100,
                "score": 165.62
            },
            {
                "indicator": "TLD Rank Score",
                "normalized_score": 0,
                "score": 0.0013861177254397739
            },
            {
                "indicator": "Umbrella Block Status",
                "normalized_score": 0,
                "score": false
            }
        ],
        "risk_score": 6,
        "domain": "amazon.com"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "indicators": [
            {
                "indicator": "Geo Popularity Score",
                "normalized_score": 2,
                "score": -3.6108781699999994
            },
            {
                "indicator": "Keyword Score",
                "normalized_score": 5,
                "score": 0.05582814570422924
            },
            {
                "indicator": "Lexical",
                "normalized_score": 71,
                "score": 0.717
            },
            {
                "indicator": "Popularity 1 Day",
                "normalized_score": 100,
                "score": 167.46
            },
            {
                "indicator": "Popularity 30 Day",
                "normalized_score": 100,
                "score": 166.93
            },
            {
                "indicator": "Popularity 7 Day",
                "normalized_score": 100,
                "score": 167.07
            },
            {
                "indicator": "Popularity 90 Day",
                "normalized_score": 100,
                "score": 165.62
            },
            {
                "indicator": "TLD Rank Score",
                "normalized_score": 0,
                "score": 0.0013861177254397739
            },
            {
                "indicator": "Umbrella Block Status",
                "normalized_score": 0,
                "score": false
            }
        ],
        "risk_score": 6,
        "domain": "amazon.com"
    }
]
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

INDICATORS

RISK_SCORE

DOMAIN

[
{
"indicator": "Geo Popularity Score",
"normalized_score": 2,
"score": -3.6108781699999994
},
{
"indicator": "Keyword Score",
"normalized_score": 5,
"score": 0.05582814570422924
},
{
"indicator": "Lexical",
"normalized_score": 71,
"score": 0.717
},
{
"indicator": "Popularity 1 Day",
"normalized_score": 100,
"score": 167.46
},
{
"indicator": "Popularity 30 Day",
"normalized_score": 100,
"score": 166.93
},
{
"indicator": "Popularity 7 Day",
"normalized_score": 100,
"score": 167.07
},
{
"indicator": "Popularity 90 Day",
"normalized_score": 100,
"score": 165.62
},
{
"indicator": "TLD Rank Score",
"normalized_score": 0,
"score": 0.0013861177254397739
},
{
"indicator": "Umbrella Block Status",
"normalized_score": 0,
"score": false
}
]

6

http://amazon.com

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

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

["amazon.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "dga_score": 0,
        "perplexity": ***,
        "entropy": ***,
        "securerank2": 100,
        "pagerank": ***,
        "asn_score": -0.014507135255556622,
        "prefix_score": -0.21703938879840215,
        "rip_score": -0.27682905786808826,
        "popularity": 100,
        "fastflux": false,
        "geodiversity": [
            [
                "US",
                ***
            ],
            [
                "BR",
                ***
            ],
            [
                "CA",
                ***
            ],
            [
                "GB",
                ***
            ],
            [
                "IT",
                **
            ],
            [
                "IN",
                ***
            ],
            [
                "FR",
                ***
            ],
            [
                "TR",
                ***
            ],
            [
                "MX",
                ***
            ]
        ],
        "geodiversity_normalized": [
            [
                "BM",
                ***
            ],
            [
                "LY",
                ***
            ],
            [
                "GQ",
                ***
            ],
            [
                "YE",
                ***
            ],
            [
                "DJ",
                ***
            ],
            [
                "MW",
                ***
            ],
            [
                "ZW",
                ***
            ],
            [
                "GP",
                ***
            ]
        ],
        "tld_geodiversity": [],
        "geoscore": 0,
        "ks_test": 0,
        "attack": "",
        "threat_type": "",
        "found": true,
        "domain": "amazon.com"
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "dga_score": 0,
        "perplexity": ***,
        "entropy": ***,
        "securerank2": 100,
        "pagerank": ***,
        "asn_score": -0.014507135255556622,
        "prefix_score": -0.21703938879840215,
        "rip_score": -0.27682905786808826,
        "popularity": 100,
        "fastflux": false,
        "geodiversity": [
            [
                "US",
                ***
            ],
            [
                "BR",
                ***
            ],
            [
                "CA",
                ***
            ],
            [
                "GB",
                ***
            ],
            [
                "IT",
                **
            ],
            [
                "IN",
                ***
            ],
            [
                "FR",
                ***
            ],
            [
                "TR",
                ***
            ],
            [
                "MX",
                ***
            ]
        ],
        "geodiversity_normalized": [
            [
                "BM",
                ***
            ],
            [
                "LY",
                ***
            ],
            [
                "GQ",
                ***
            ],
            [
                "YE",
                ***
            ],
            [
                "DJ",
                ***
            ],
            [
                "MW",
                ***
            ],
            [
                "ZW",
                ***
            ],
            [
                "GP",
                ***
            ]
        ],
        "tld_geodiversity": [],
        "geoscore": 0,
        "ks_test": 0,
        "attack": "",
        "threat_type": "",
        "found": true,
        "domain": "amazon.com"
    }
]
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

DGA_SCORE

PERPLEXITY

ENTROPY

SECURERANK2

PAGERANK

ASN_SCORE

PREFIX_SCORE

RIP_SCORE

POPULARITY

FASTFLUX

GEODIVERSITY

GEODIVERSITY_NORMALIZED

TLD_GEODIVERSITY

GEOSCORE

KS_TEST

ATTACK

THREAT_TYPE

FOUND

DOMAIN

0

100

***

-0.0145071352555566

-0.217039388798402

-0.276829057868088

100

False

[
{
"country": "US",
"score": ***
},
{
"country": "BR",
"score": ***
}
]

[]

0

0

True

http://amazon.com

Error Handling

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

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "meta": {
            "page": 1,
            "limit": 200,
            "prev": false,
            "next": false
        },
        "data": [
            {
                "id": ***,
                "name": "***.com",
                "lastSeenAt": 1627688341
            },
            {
                "id": ***,
                "name": "***.com",
                "lastSeenAt": 1627520863
            },
            {
                "id": ***,
                "name": "***.com",
                "lastSeenAt": 1627530853
            },
            {
                "id": ***,
                "name": "***.com",
                "lastSeenAt": 1627577025
            },
            {
                "id": *8*,
                "name": "***.com",
                "lastSeenAt": 1627673752
            },
            {
                "id": ***,
                "name": "***.com",
                "lastSeenAt": 1627688661
            }
        ]
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.data in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "id": ***,
        "name": "***.com",
        "lastSeenAt": 1627688341
    },
    {
        "id": ***,
        "name": "***.com",
        "lastSeenAt": 1627520863
    },
    {
        "id": ***,
        "name": "***.com",
        "lastSeenAt": 1627530853
    },
    {
        "id": ***,
        "name": "***.com",
        "lastSeenAt": 1627577025
    },
    {
        "id": *8*,
        "name": "***.com",
        "lastSeenAt": 1627673752
    },
    {
        "id": ***,
        "name": "***.com",
        "lastSeenAt": 1627688661
    }
]
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 
{
    "IDs": [
        ***,
        ***,
        ***,
        ***,
        ***
    ],
    "Names": [
        "***.com",
        "***.com",
        "***.com",
        "***.com",
        "***.com"
    ],
    "LastSeenTimestamps": [
        1627688341,
        1627520863,
        1627530853,
        1627577025,
        1627673752
    ]
}
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

ID

NAME

LASTSEENAT

***

***.com

1627688341

***

***.com

1627520863

***

***.com

1627530853

***

***.com

1627577025

***

***.com

1627673752

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.

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.

["***","***"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "id": "***,***,***,***"
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "id": "***,***,***,***"
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "ID": "***,***,***,***"
}
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

CODE 
No Sample Data

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.

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.

["9.9.9.10","9.9.9.11"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "status": {
        "code": 200,
        "text": "OK"
    },
    "data": {
        "id": ***,
        "organizationId": ***,
        "access": "allow",
        "isGlobal": true,
        "name": "Global Allow List",
        "thirdpartyCategoryId": null,
        "createdAt": "2021-07-26T10:02:13-07:00",
        "modifiedAt": "2021-08-05T15:39:54-07:00",
        "isMspDefault": false,
        "markedForDeletion": false,
        "bundleTypeId": 1,
        "meta": {
            "destinationCount": 9
        }
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.data in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
{
    "id": ***,
    "organizationId": ***,
    "access": "allow",
    "isGlobal": true,
    "name": "Global Allow List",
    "thirdpartyCategoryId": null,
    "createdAt": "2021-07-26T10:02:13-07:00",
    "modifiedAt": "2021-08-05T15:39:54-07:00",
    "isMspDefault": false,
    "markedForDeletion": false,
    "bundleTypeId": 1,
    "meta": {
        "destinationCount": 9
    }
}
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

id

***

organizationId

***

access

allow

isGlobal

True

name

Global Allow List

thirdpartyCategoryId

createdAt

7/26/2021 10:02:13 AM

modifiedAt

8/5/2021 3:39:54 PM

isMspDefault

False

markedForDeletion

False

bundleTypeId

1

meta

{

"destinationCount": 9

}

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.

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.

["google.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "administrativeContactFax": null,
        "whoisServers": "whois.server.com",
        "addresses": [],
        "administrativeContactName": null,
        "zoneContactEmail": null,
        "billingContactFax": null,
        "administrativeContactTelephoneExt": null,
        "administrativeContactEmail": null,
        "technicalContactEmail": null,
        "technicalContactFax": null,
        "nameServers": [
            "ns1.google.com",
            "ns2.google.com",
            "ns3.google.com",
            "ns4.google.com"
        ],
        "zoneContactName": null,
        "billingContactPostalCode": null,
        "zoneContactFax": null,
        "registrantTelephoneExt": null,
        "zoneContactFaxExt": null,
        "technicalContactTelephoneExt": null,
        "billingContactCity": null,
        "zoneContactStreet": [],
        "created": "1997-09-15",
        "administrativeContactCity": null,
        "registrantName": null,
        "zoneContactCity": null,
        "domainName": "google.com",
        "zoneContactPostalCode": null,
        "administrativeContactFaxExt": null,
        "technicalContactCountry": "UNITED STATES",
        "registrarIANAID": "292",
        "updated": "2019-09-09",
        "administrativeContactStreet": [],
        "billingContactEmail": null,
        "status": [
            "clientDeleteProhibited clientTransferProhibited clientUpdateProhibited serverDeleteProhibited serverTransferProhibited serverUpdateProhibited"
        ],
        "registrantCity": null,
        "billingContactCountry": null,
        "expires": "2028-09-14",
        "technicalContactStreet": [],
        "registrantOrganization": "Google LLC",
        "billingContactStreet": [],
        "registrarName": "MarkMonitor, Inc.",
        "registrantPostalCode": null,
        "zoneContactTelephone": null,
        "registrantEmail": null,
        "technicalContactFaxExt": null,
        "technicalContactOrganization": "Google LLC",
        "emails": [],
        "registrantStreet": [],
        "technicalContactTelephone": null,
        "technicalContactState": "CA",
        "technicalContactCity": null,
        "registrantFax": null,
        "registrantCountry": "UNITED STATES",
        "billingContactFaxExt": null,
        "timestamp": null,
        "zoneContactOrganization": null,
        "administrativeContactCountry": "UNITED STATES",
        "billingContactName": null,
        "registrantState": "CA",
        "registrantTelephone": null,
        "administrativeContactState": "CA",
        "registrantFaxExt": null,
        "technicalContactPostalCode": null,
        "zoneContactTelephoneExt": null,
        "administrativeContactOrganization": "Google LLC",
        "billingContactTelephone": null,
        "billingContactTelephoneExt": null,
        "zoneContactState": null,
        "administrativeContactTelephone": null,
        "billingContactOrganization": null,
        "technicalContactName": null,
        "administrativeContactPostalCode": null,
        "zoneContactCountry": null,
        "billingContactState": null,
        "auditUpdatedDate": "2021-06-25 06:47:48 UTC",
        "recordExpired": false,
        "timeOfLatestRealtimeCheck": 1624607404215,
        "hasRawText": true
    }
]
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "administrativeContactFax": null,
        "whoisServers": "whois.server.com",
        "addresses": [],
        "administrativeContactName": null,
        "zoneContactEmail": null,
        "billingContactFax": null,
        "administrativeContactTelephoneExt": null,
        "administrativeContactEmail": null,
        "technicalContactEmail": null,
        "technicalContactFax": null,
        "nameServers": [
            "ns1.google.com",
            "ns2.google.com",
            "ns3.google.com",
            "ns4.google.com"
        ],
        "zoneContactName": null,
        "billingContactPostalCode": null,
        "zoneContactFax": null,
        "registrantTelephoneExt": null,
        "zoneContactFaxExt": null,
        "technicalContactTelephoneExt": null,
        "billingContactCity": null,
        "zoneContactStreet": [],
        "created": "1997-09-15",
        "administrativeContactCity": null,
        "registrantName": null,
        "zoneContactCity": null,
        "domainName": "google.com",
        "zoneContactPostalCode": null,
        "administrativeContactFaxExt": null,
        "technicalContactCountry": "UNITED STATES",
        "registrarIANAID": "***",
        "updated": "2019-09-09",
        "administrativeContactStreet": [],
        "billingContactEmail": null,
        "status": [
            "clientDeleteProhibited clientTransferProhibited clientUpdateProhibited serverDeleteProhibited serverTransferProhibited serverUpdateProhibited"
        ],
        "registrantCity": null,
        "billingContactCountry": null,
        "expires": "2028-09-14",
        "technicalContactStreet": [],
        "registrantOrganization": "Google LLC",
        "billingContactStreet": [],
        "registrarName": "MarkMonitor, Inc.",
        "registrantPostalCode": null,
        "zoneContactTelephone": null,
        "registrantEmail": null,
        "technicalContactFaxExt": null,
        "technicalContactOrganization": "Google LLC",
        "emails": [],
        "registrantStreet": [],
        "technicalContactTelephone": null,
        "technicalContactState": "CA",
        "technicalContactCity": null,
        "registrantFax": null,
        "registrantCountry": "UNITED STATES",
        "billingContactFaxExt": null,
        "timestamp": null,
        "zoneContactOrganization": null,
        "administrativeContactCountry": "UNITED STATES",
        "billingContactName": null,
        "registrantState": "CA",
        "registrantTelephone": null,
        "administrativeContactState": "CA",
        "registrantFaxExt": null,
        "technicalContactPostalCode": null,
        "zoneContactTelephoneExt": null,
        "administrativeContactOrganization": "Google LLC",
        "billingContactTelephone": null,
        "billingContactTelephoneExt": null,
        "zoneContactState": null,
        "administrativeContactTelephone": null,
        "billingContactOrganization": null,
        "technicalContactName": null,
        "administrativeContactPostalCode": null,
        "zoneContactCountry": null,
        "billingContactState": null,
        "auditUpdatedDate": "2021-06-25 06:47:48 UTC",
        "recordExpired": false,
        "timeOfLatestRealtimeCheck": 1624607404215,
        "hasRawText": true
    }
]
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

ADMINISTRATIVECONTACTFAX

WHOISSERVERS

ADDRESSES

ADMINISTRATIVECONTACTNAME

ZONECONTACTEMAIL

BILLINGCONTACTFAX

ADMINISTRATIVECONTACTTELEPHONEEXT

ADMINISTRATIVECONTACTEMAIL

TECHNICALCONTACTEMAIL

TECHNICALCONTACTFAX

NAMESERVERS

ZONECONTACTNAME

BILLINGCONTACTPOSTALCODE

ZONECONTACTFAX

REGISTRANTTELEPHONEEXT

ZONECONTACTFAXEXT

TECHNICALCONTACTTELEPHONEEXT

BILLINGCONTACTCITY

ZONECONTACTSTREET

CREATED

ADMINISTRATIVECONTACTCITY

REGISTRANTNAME

ZONECONTACTCITY

DOMAINNAME

ZONECONTACTPOSTALCODE

ADMINISTRATIVECONTACTFAXEXT

TECHNICALCONTACTCOUNTRY

REGISTRARIANAID

UPDATED

ADMINISTRATIVECONTACTSTREET

BILLINGCONTACTEMAIL

STATUS

REGISTRANTCITY

BILLINGCONTACTCOUNTRY

EXPIRES

TECHNICALCONTACTSTREET

REGISTRANTORGANIZATION

BILLINGCONTACTSTREET

REGISTRARNAME

REGISTRANTPOSTALCODE

ZONECONTACTTELEPHONE

REGISTRANTEMAIL

TECHNICALCONTACTFAXEXT

TECHNICALCONTACTORGANIZATION

EMAILS

REGISTRANTSTREET

TECHNICALCONTACTTELEPHONE

TECHNICALCONTACTSTATE

TECHNICALCONTACTCITY

REGISTRANTFAX

REGISTRANTCOUNTRY

BILLINGCONTACTFAXEXT

TIMESTAMP

ZONECONTACTORGANIZATION

ADMINISTRATIVECONTACTCOUNTRY

BILLINGCONTACTNAME

REGISTRANTSTATE

REGISTRANTTELEPHONE

ADMINISTRATIVECONTACTSTATE

REGISTRANTFAXEXT

TECHNICALCONTACTPOSTALCODE

ZONECONTACTTELEPHONEEXT

ADMINISTRATIVECONTACTORGANIZATION

BILLINGCONTACTTELEPHONE

BILLINGCONTACTTELEPHONEEXT

ZONECONTACTSTATE

ADMINISTRATIVECONTACTTELEPHONE

BILLINGCONTACTORGANIZATION

TECHNICALCONTACTNAME

ADMINISTRATIVECONTACTPOSTALCODE

ZONECONTACTCOUNTRY

BILLINGCONTACTSTATE

AUDITUPDATEDDATE

RECORDEXPIRED

TIMEOFLATESTREALTIMECHECK

HASRAWTEXT

whois.server.com

[]

[
"ns1.google.com",
"ns2.google.com",
"ns3.google.com",
"ns4.google.com"
]

[]

1997-09-15

http://google.com

UNITED STATES

***

2019-09-09

[]

[
"clientDeleteProhibited clientTransferProhibited clientUpdateProhibited serverDeleteProhibited serverTransferProhibited serverUpdateProhibited"
]

2028-09-14

[]

Google LLC

[]

MarkMonitor, Inc.

Google LLC

[]

[]

CA

UNITED STATES

UNITED STATES

CA

CA

Google LLC

2021-06-25 06:47:48 UTC

False

1624607404215

True

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.

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.

["test@example.com"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "admin@google.com": {
        "totalResults": ***,
        "offset": 0,
        "moreDataAvailable": false,
        "limit": 500,
        "sortField": "domain name [default]",
        "domains": [
            {
                "domain": "test.com",
                "current": false
            },
            {
                "domain": "example.com",
                "current": false
            }
        ],
        "email": "test@example.com"
    }
}
Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE 
[
    {
        "totalResults": 135,
        "totalResults": ***,
        "offset": 0,
        "moreDataAvailable": false,
        "limit": 500,
        "sortField": "domain name [default]",
        "domains": [
            {
                "domain": "test.com",
                "current": false
            },
            {
                "domain": "example.com",
                "current": false
            }
        ],
        "email": "admin@google.com"
    }
]
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

test@example.com

{

"totalResults": 135,

"offset": 0,

"moreDataAvailable": false,

"limit": 500,

"sortField": "domain name [default]",

"domains": [

{

"domain": "http://test.com ",

"current": false

},

{

"domain": "example.com",

"current": false

},

],

"email": "test@example.com"

}

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.

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 you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

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

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
No Sample Data

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close