Cisco Umbrella Investigate
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
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.
Query Domain
Queries Cisco Umbrella information on the domain, including status and categorization.
Cisco's documentation for this action can be found here.
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.
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.
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.
Get Passive DNS History For Domain
Returns passive DNS (pDNS) history for a domain.
Cisco's documentation for this action can be found here.
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.
Whois Domain
Returns WHOIS information for the specified domain.
Cisco's documentation for this action can be found here.
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 β Secure Access: 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 | |
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 |