--- title: Cisco Umbrella Investigate slug: connectors/cisco-umbrella-investigate docTags: createdAt: 2026-06-09T16:30:13.380Z --- Cisco Umbrella Investigate provides threat intelligence insights into domain activities, enhancing security operations. Cisco Umbrella Investigate provides a comprehensive suite of domain and IP intelligence services, offering insights into domain risk scores, security categorizations, passive DNS data, and WHOIS information. By integrating with Swimlane Turbine, users can automate the retrieval of critical domain and IP data, enhancing threat detection and response capabilities. This integration empowers security teams to streamline their workflows, reduce manual research, and make informed decisions quickly, leveraging Cisco Umbrella's robust data for proactive security measures. ### Limitations None to date. ### Supported Versions This Cisco Umbrella Investigate connector uses the Umbrella Investigate API (investigate.api.opendns.com). ### Additional Docs - [Cisco Cloud Security API – Umbrella](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview) - [Get Domain Status and Categorization](https://developer.cisco.com/docs/cloud-security/#!get-domain-status-and-categorization) - [Umbrella Investigate Documentation](https://docs.umbrella.com/deployment-umbrella/docs/manage-umbrella-investigate) ## Configuration ### Prerequisites Before you can use the Cisco Umbrella Investigate connector for Turbine, you'll need access to the Cisco Umbrella API. This requires the following: - Custom authentication using OAuth 2.0 client credentials with the following parameters: - URL: The base URL for Umbrella or Secure Access Investigate. - API Key: A unique key provided by Cisco for API access. - Key Secret: A secret key associated with the API Key for secure authentication. ## Authentication Methods ### HTTP Bearer Authentication - **URL:** The endpoint URL for the Umbrella Investigate API (default: `https://investigate.api.opendns.com/`). - **Token:** The API token provided by Umbrella Investigate. Create an Investigate API token in the Umbrella dashboard. - **Verify SSL Certificates:** (Optional) Enable or disable SSL certificate verification. - **HTTP(s) Proxy:** (Optional) A proxy URL to route requests through. ## Capabilities This Cisco Umbrella Investigate connector provides the following capabilities: - Get Domain Status and Categorization - Query Domain - Domain Risk Score - Security Information for a Domain - Related Domains for a Domain - Get Passive DNS History For Domain - Get Passive DNS Results By IP - Whois Domain ### Get Domain Status and Categorization Returns the status and categorization for a domain, including status (-1 malicious, 1 safe, 0 undetermined), security categories, and content categories. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!get-domain-status-and-categorization). ### Query Domain Queries Cisco Umbrella information on the domain, including status and categorization. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Domain Risk Score Returns the Umbrella Investigate risk score for a domain based on lexical characteristics, query patterns, and other indicators. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Security Information for a Domain Returns multiple security scores and features for a domain (e.g. DGA score, entropy, geodiversity, popularity). Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Related Domains for a Domain Returns a list of domain names that frequently co-occur with the given domain in queries. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Get Passive DNS History For Domain Returns passive DNS (pDNS) history for a domain. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Get Passive DNS Results By IP Returns passive DNS results for a given IP address. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). ### Whois Domain Returns WHOIS information for the specified domain. Cisco's documentation for this action can be found [here](https://developer.cisco.com/docs/cloud-security/#!umbrella-api-reference-overview). # Configurations ## Cisco Umbrella OAuth 2.0 Client Authentication Authenticates with API Key ID and Key Secret via OAuth 2.0 client credentials. Use the Umbrella or Secure Access Investigate base URL. ### Configuration Parameters | **Parameter** | **Description** | **Type** | **Required** | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | | url | Investigate API base URL. Umbrella: [https://api.umbrella.com/investigate/v2](https://api.umbrella.com/investigate/v2) — Secure Access: [https://api.sse.cisco.com/investigate/v2](https://api.sse.cisco.com/investigate/v2) | string | Required | | api\_key | API Key ID. | string | Required | | api\_secret | API Key Secret. | string | Required | | verify\_ssl | Verify SSL certificate | boolean | Optional | | http\_proxy | A proxy to route requests through. | string | Optional | # Actions ## Domain Risk Score Retrieve the risk score for a domain from Cisco Umbrella Investigate, based on lexical analysis and query patterns. Requires the domain as a path parameter. ### Endpoint - **URL:** `domains/risk-score/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ------------------------------------------- | | `path_parameters.domain` | string | Required | Parameters for the Domain Risk Score action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ----------------------------- | -------- | ---------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `indicators` | array | Output field: indicators | | `indicators.indicator` | string | Output field: indicators.indicator | | `indicators.indicator_id` | string | Unique identifier | | `indicators.normalized_score` | number | Score value | | `indicators.score` | boolean | Score value | | `risk_score` | number | Score value | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 19:56:23 GMT","Content-Type":"application/json","Content-Length":"1001","Connection":"keep-alive","Vary":"Accept-Encoding","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Co...","Access-Control-Expose-Headers":"Content-Length,Content-Range","...` ## Get Domain Status and Categorization Retrieve domain status, security, and content categorizations from Cisco Umbrella Investigate for a specified domain. ### Endpoint - **URL:** `domains/categorization/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ---------------------------------------------------------- | | `path_parameters.domain` | string | Required | The domain name to look up (e.g. cisco.com, umbrella.com). | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ------------------------------- | -------- | ------------------------------------------ | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `cisco.com` | object | Output field: cisco.com | | `cisco.com.status` | number | -1 = malicious, 1 = safe, 0 = undetermined | | `cisco.com.security_categories` | array | Security category IDs for this domain. | | `cisco.com.content_categories` | array | Content category IDs for this domain. | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 20:31:00 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` ## Get Passive DNS History For Domain Retrieve the passive DNS history for a specified domain from Cisco Umbrella Investigate, filtering records by security categories. Requires domain as a path parameter. ### Endpoint - **URL:** `/pdns/name/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ------------------------------------------------------------ | | `path_parameters.domain` | string | Required | Parameters for the Get Passive DNS History For Domain action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | -------------------------------------- | -------- | --------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `records` | array | Output field: records | | `records.minTtl` | number | Output field: records.minTtl | | `records.maxTtl` | number | Output field: records.maxTtl | | `records.firstSeen` | number | Output field: records.firstSeen | | `records.lastSeen` | number | Output field: records.lastSeen | | `records.name` | string | Name of the resource | | `records.type` | string | Type of the resource | | `records.rr` | string | Output field: records.rr | | `records.securityCategories` | array | Output field: records.securityCategories | | `records.securityCategories.file_name` | string | Name of the resource | | `records.securityCategories.file` | string | Output field: records.securityCategories.file | | `records.contentCategories` | array | Response content | | `records.contentCategories.file_name` | string | Name of the resource | | `records.contentCategories.file` | string | Response content | | `records.lastSeenISO` | string | Output field: records.lastSeenISO | | `records.firstSeenISO` | string | Output field: records.firstSeenISO | | `pageInfo` | object | Output field: pageInfo | | `pageInfo.hasMoreRecords` | boolean | Output field: pageInfo.hasMoreRecords | | `pageInfo.offset` | number | Output field: pageInfo.offset | | `pageInfo.limit` | number | Output field: pageInfo.limit | | `pageInfo.totalNumRecords` | number | Output field: pageInfo.totalNumRecords | | `recordInfo` | object | Output field: recordInfo | | `recordInfo.minTtl` | number | Output field: recordInfo.minTtl | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 19:45:45 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Strict-Transport-Security":"max-age=15768000; includeSubDomains"},"reason":"Internal Server Error","json_body":{"records":[{},{}],"pageInfo":{"hasMoreRecords":true,"offset":0,"limit":500,"totalNumRecords":2544},"recordInfo":{"minTtl":3,"maxTtl":604800,"totalMaliciousDomain":0}}}` ## Get Passive DNS Results By IP Retrieve passive DNS records filtered by security categories for a specified IP address using Cisco Umbrella Investigate. ### Endpoint - **URL:** `/pdns/ip/{{ip}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | -------------------- | -------- | ------------ | ------------------------------------------------------- | | `path_parameters.ip` | string | Required | Parameters for the Get Passive DNS Results By IP action | ### Input Example `{"path_parameters":{"ip":"3.219.99.232"}}` ### Output | **Parameter** | **Type** | **Description** | | -------------------------------------- | -------- | --------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `records` | array | Output field: records | | `records.minTtl` | number | Output field: records.minTtl | | `records.maxTtl` | number | Output field: records.maxTtl | | `records.firstSeen` | number | Output field: records.firstSeen | | `records.lastSeen` | number | Output field: records.lastSeen | | `records.name` | string | Name of the resource | | `records.type` | string | Type of the resource | | `records.rr` | string | Output field: records.rr | | `records.securityCategories` | array | Output field: records.securityCategories | | `records.securityCategories.file_name` | string | Name of the resource | | `records.securityCategories.file` | string | Output field: records.securityCategories.file | | `records.contentCategories` | array | Response content | | `records.contentCategories.file_name` | string | Name of the resource | | `records.contentCategories.file` | string | Response content | | `records.lastSeenISO` | string | Output field: records.lastSeenISO | | `records.firstSeenISO` | string | Output field: records.firstSeenISO | | `pageInfo` | object | Output field: pageInfo | | `pageInfo.hasMoreRecords` | boolean | Output field: pageInfo.hasMoreRecords | | `pageInfo.offset` | number | Output field: pageInfo.offset | | `pageInfo.limit` | number | Output field: pageInfo.limit | | `pageInfo.totalNumRecords` | number | Output field: pageInfo.totalNumRecords | | `recordInfo` | object | Output field: recordInfo | | `recordInfo.minTtl` | number | Output field: recordInfo.minTtl | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 19:37:54 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` ## Query Domain Retrieve Cisco Umbrella Investigate data for a specified domain. Requires the domain as a path parameter. ### Endpoint - **URL:** `domains/categorization/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | -------------------------------------- | | `path_parameters.domain` | string | Required | Parameters for the Query Domain action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ----------------------------------------- | -------- | ------------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `cisco.com` | object | Output field: cisco.com | | `cisco.com.status` | number | Status value | | `cisco.com.security_categories` | array | Output field: cisco.com.security\_categories | | `cisco.com.security_categories.file_name` | string | Name of the resource | | `cisco.com.security_categories.file` | string | Output field: cisco.com.security\_categories.file | | `cisco.com.content_categories` | array | Response content | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 20:31:00 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` ## Related Domains for a Domain Retrieve domains frequently requested around the same time as a specified domain in Cisco Umbrella Investigate. Requires the domain as a path parameter. ### Endpoint - **URL:** `/links/name/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ------------------------------------------------------ | | `path_parameters.domain` | string | Required | Parameters for the Related Domains for a Domain action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `tb1` | array | Output field: tb1 | | `tb1.0` | string | Output field: tb1.0 | | `tb1.1` | number | Output field: tb1.1 | | `found` | boolean | Output field: found | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 20:35:12 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` ## Security Information for a Domain Retrieve a comprehensive list of security scores and features for a specified domain using Cisco Umbrella Investigate. Requires the domain as a path parameter. ### Endpoint - **URL:** `security/name/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | ----------------------------------------------------------- | | `path_parameters.domain` | string | Required | Parameters for the Security Information for a Domain action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ---------------------------- | -------- | ---------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `dga_score` | number | Score value | | `perplexity` | number | Output field: perplexity | | `entropy` | number | Output field: entropy | | `securerank2` | number | Output field: securerank2 | | `pagerank` | number | Output field: pagerank | | `asn_score` | number | Score value | | `prefix_score` | number | Score value | | `rip_score` | number | Score value | | `popularity` | number | Output field: popularity | | `fastflux` | boolean | Output field: fastflux | | `geodiversity` | array | Output field: geodiversity | | `geodiversity.0` | string | Output field: geodiversity.0 | | `geodiversity.1` | number | Output field: geodiversity.1 | | `geodiversity_normalized` | array | Output field: geodiversity\_normalized | | `geodiversity_normalized.0` | string | Output field: geodiversity\_normalized.0 | | `geodiversity_normalized.1` | number | Output field: geodiversity\_normalized.1 | | `tld_geodiversity` | array | Output field: tld\_geodiversity | | `tld_geodiversity.file_name` | string | Name of the resource | | `tld_geodiversity.file` | string | Output field: tld\_geodiversity.file | | `geoscore` | number | Score value | | `ks_test` | number | Output field: ks\_test | | `attack` | string | Output field: attack | | `threat_type` | string | Type of the resource | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 20:26:42 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` ## Whois Domain Retrieve WHOIS information for a specified domain using Cisco Umbrella Investigate. Requires the domain as a path parameter. ### Endpoint - **URL:** `/whois/{{domain}}` - **Method:** `GET` ### Input | **Argument Name** | **Type** | **Required** | **Description** | | ------------------------ | -------- | ------------ | -------------------------------------- | | `path_parameters.domain` | string | Required | Parameters for the Whois Domain action | ### Input Example `{"path_parameters":{"domain":"cisco.com"}}` ### Output | **Parameter** | **Type** | **Description** | | ----------------------------------- | -------- | ----------------------------------------------- | | `status_code` | number | HTTP status code of the response | | `reason` | string | Response reason phrase | | `administrativeContactFax` | object | Output field: administrativeContactFax | | `whoisServers` | string | Output field: whoisServers | | `addresses` | array | Output field: addresses | | `administrativeContactName` | string | Name of the resource | | `zoneContactEmail` | object | Output field: zoneContactEmail | | `billingContactFax` | object | Output field: billingContactFax | | `administrativeContactTelephoneExt` | object | Output field: administrativeContactTelephoneExt | | `administrativeContactEmail` | string | Output field: administrativeContactEmail | | `technicalContactEmail` | string | Output field: technicalContactEmail | | `technicalContactFax` | string | Output field: technicalContactFax | | `nameServers` | array | Name of the resource | | `zoneContactName` | object | Name of the resource | | `billingContactPostalCode` | object | Output field: billingContactPostalCode | | `zoneContactFax` | object | Output field: zoneContactFax | | `registrantTelephoneExt` | object | Output field: registrantTelephoneExt | | `zoneContactFaxExt` | object | Output field: zoneContactFaxExt | | `technicalContactTelephoneExt` | object | Output field: technicalContactTelephoneExt | | `billingContactCity` | object | Output field: billingContactCity | | `zoneContactStreet` | array | Output field: zoneContactStreet | | `zoneContactStreet.file_name` | string | Name of the resource | | `zoneContactStreet.file` | string | Output field: zoneContactStreet.file | | `created` | string | Output field: created | | `administrativeContactCity` | string | Output field: administrativeContactCity | ### Output Example `{"status_code":200,"response_headers":{"Server":"nginx","Date":"Thu, 09 Feb 2023 20:10:06 GMT","Content-Type":"application/json; charset=UTF-8","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding","X-Frame-Options":"SAMEORIGIN, SAMEORIGIN","X-XSS-Protection":"1; mode=block, 1; mode=block","Access-Control-Allow-Origin":"https://dashboard.umbrella.com","Access-Control-Allow-Methods":"GET, POST, OPTIONS","Access-Control-Allow-Headers":"Authorization, Accept,DNT,User-Agen...` # Response Headers | **Header** | **Description** | **Example** | | -------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Access-Control-Allow-Credentials | HTTP response header: Access-Control-Allow-Credentials | true | | Access-Control-Allow-Headers | HTTP response header: Access-Control-Allow-Headers | Authorization, Accept,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,X-SGraph-Is-Research | | Access-Control-Allow-Methods | HTTP response header: Access-Control-Allow-Methods | GET, POST, OPTIONS | | Access-Control-Allow-Origin | HTTP response header: Access-Control-Allow-Origin | [https://dashboard.umbrella.com](https://dashboard.umbrella.com) | | Access-Control-Expose-Headers | HTTP response header: Access-Control-Expose-Headers | Content-Length,Content-Range | | Connection | HTTP response header: Connection | keep-alive | | Content-Length | The length of the response body in bytes | 1001 | | Content-Type | The media type of the resource | application/json | | Date | The date and time at which the message was originated | Thu, 09 Feb 2023 19:45:45 GMT | | Server | Information about the software used by the origin server | nginx | | Strict-Transport-Security | HTTP response header: Strict-Transport-Security | max-age=15768000; includeSubDomains | | Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked | | Vary | HTTP response header: Vary | Accept-Encoding | | X-Content-Type-Options | HTTP response header: X-Content-Type-Options | nosniff | | X-Frame-Options | HTTP response header: X-Frame-Options | SAMEORIGIN, SAMEORIGIN | | X-XSS-Protection | HTTP response header: X-XSS-Protection | 1; mode=block |