Cisco Umbrella Investigate
This Integration is part of the Cisco Umbrella Investigate Pack.#
Use the Cisco Umbrella integration to manage online threats.
Configure Cisco Umbrella Investigate - Python on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for Cisco Umbrella Investigate - Python.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Cisco Umbrella API token
- Source Reliability.
- Use system proxy settings
- Trust any certificate (not secure)
- Base URL
- DBot Score Malicious Threshold
- Click Test to validate the URLs, token, and connection.
How DBot Score Malicious Threshold is Calculated
The DBot Score Malicious Threshold is calculated by taking the lower of two Cisco scores: secure rank and domain status .
The DBot Score will be 3 (bad) in these cases:
- The secure rank score is lower than the threshold score
- The domain status is -1
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Get a domain category: umbrella-domain-categorization/investigate-umbrella-domain-categorization
- Get co-occurences for a domain: umbrella-domain-co-occurrences/investigate-umbrella-domain-co-occurrences
- Get a list of domain names requested the same time as a specified domain: umbrella-domain-related/investigate-umbrella-domain-related
- Get domain security data: umbrella-domain-security/investigate-umbrella-domain-security
- Query the DNS database for domains: umbrella-domain-dns-history/investigate-umbrella-domain-dns-history
- Query the DNS database for IPs: umbrella-ip-dns-history/investigate-umbrella-ip-dns-history
- Get malicious domains associated with an IP address: umbrella-ip-malicious-domains/investigate-umbrella-ip-malicious-domains
- Get a list of domains that match a regular expression (regex): umbrella-domain-search/investigate-umbrella-domain-search
- Get the reputation for a domain: domain
- Get a list of domain names requested the same time as a specified domain and a list of co-occurrences: umbrella-get-related-domains
- List all classifiers for a domain: umbrella-get-domain-classifiers
- Get the number of DNS queries for a domain: umbrella-get-domain-queryvolume
- Get domain security data: umbrella-get-domain-details
- Get domains associated with registrar email addresses: umbrella-get-domains-for-email-registrar
- Get all domains for a nameserver: umbrella-get-domains-for-nameserver
- Get WHOIS data for a domain: umbrella-get-whois-for-domain
- Get malicious domains associated with an IP address: umbrella-get-malicious-domains-for-ip
- Get a list of domains that match a regular expressions (regex): umbrella-get-domains-using-regex
- Query when a domain was attributed to a security organization or as a threat type: umbrella-get-domain-timeline
- Query when an IP address was attributed to a security organization or as a threat type: umbrella-get-ip-timeline
- Query when a URL was attributed to a security organization or as a threat type: umbrella-get-url-timeline
1. Get a domain category
Returns the category of a domain, e.g.,
domain=amazon.com
returns
Ecommerce/Shopping
.
Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.
Base Command
umbrella-domain-categorization
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain to categorize (e.g., amazon.com) | Required |
Context Output
| Path | Description |
|---|---|
| Domain.Name | Domain name |
| Domain.SecurityCategories | The Umbrella security category, or categories, that match this domain |
| Domain.ContentCategories | The Umbrella content category or categories that match this domain |
| Domain.Malicious.Vendor | For malicious domains, the vendor that made the decision |
| Domain.Malicious.Description | For malicious domains, the reason for the vendor to make the decision |
Command Example
!umbrella-domain-categorization domain=cnn.com
Context Example
Domain:{} 2 items
ContentCategories:News/Media
Name:cnn.com
Human Readable Output
2. Get co-occurences for a domain
Gets a list of related domains and returns a list of co-occurences for the specified domain. A co-occurrence is when two or more domains are being accessed by the same users within a short time frame. Co-occurrence are not necessarily negative. Legitimate sites co-occur with each other as a part of normal web activity. However, unusual or suspicious co-occurence can provide additional information regarding attacks.
Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.
Base Command
umbrella-domain-co-occurrences
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | Enter a domain (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Domain.Name | string | Domain name |
| Domain.CoOccurrences.Score | number | Domain score (between 0 and 1) |
| Domain.CoOccurrences.Name | string | Domain name |
Command Example
!umbrella-domain-co-occurrences domain=walla.com
Context Example
Domain:{} 2 items
CoOccurrences:[] 1 item
0:{} 2 items
Name:walla.co.il
Score:1
Name:walla.com
Human Readable Output
3. Get a list of domain names requested the same time as a specified domain
Returns a list of domain names that are frequently seen requested around the same time as the specified domain name (up to 60 seconds before or after). The returned domain names are ones that are not frequently associated with other domain names.
Base Command
umbrella-domain-related
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | Domain name (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Domain.Name | string | Domain name |
| Domain.Related.Score | number | This is a score reflecting the number of client IPs looking up related sites within 60 seconds of the original request |
| Domain.Related.Name | string | Related domain name |
Command Example
!umbrella-domain-related domain=walla.com
Context Example
Domain:{} 2 items
Name:walla.com
Related:[] 9 items
0:{} 2 items
Name:c3s2.iphmx.com
Score:6
1:{} 2 items
Name:google.co.ma
Score:6
2:{} 2 items
Name:email.footsmart.com
Score:5
3:{} 2 items
Name:link.expediamail.com
Score:4
4:{} 2 items
Name:cdn.lemediavault.com
Score:4
5:{} 2 items
Name:click.royalcaribbeanmarketing.com
Score:3
6:{} 2 items
Name:e2.overtons.com
Score:3
7:{} 2 items
Name:link.trustpilot.com
Score:3
8:{} 2 items
Name:tr.subscribermail.com
Score:3
Human Readable Output
4. Get domain security data
This contains multiple scores or security features, each of which can be used to determine relevant datapoints to build insight on the reputation or security risk posed by the site. For more security information about this specific domain, see the Cisco Umbrella documentation.
Base Command
umbrella-domain-security
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | Domain name (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Domain.Name | string | Domain name |
| Domain.Security.DGA | number | Domain Generation Algorithm. This score is generated based on the likeliness of the domain name being generated by an algorithm rather than a human |
| Domain.Security.Perplexity | number | A second score on the likeliness of the name to be algorithmically generated, on a scale from 0 to 1 |
| Domain.Security.Entropy | number | The number of bits required to encode the domain name, as a score |
| Domain.Security.SecureRank | number | Suspicious rank for a domain that reviews based on the lookup behavior of client IP for the domain |
| Domain.Security.PageRank | number | Popularity according to Google's pagerank algorithm |
| Domain.Security.ASNScore | unknown | ASN reputation score, ranges from -100 to 0 with -100 being very suspicious |
| Domain.Security.PrefixScore | number | Prefix ranks domains given their IP prefixes (an IP prefix is the first three octets in an IP address) and the reputation score of these prefixes. Ranges from -100 to 0, -100 being very suspicious |
| Domain.Security.RipScore | number | RIP ranks domains given their IP addresses and the reputation score of these IP addresses. Ranges from -100 to 0, -100 being very suspicious |
| Domain.Security.Popularity | number | The number of unique client IPs visiting this site, relative to the all requests to all sites |
| Domain.Security.GeoScore | number | A score that represents how far the different physical locations serving this name are from each other |
| Domain.Security.KolmoorovSmirnov | number | olmogorov–Smirnov test on geodiversity. 0 means that the client traffic matches what is expected for this TLD |
| Domain.Security.AttackName | string | The name of any known attacks associated with this domain, or blank if no known threat |
| Domain.Security.ThreatType | string | The type of the known attack, such as botnet or APT, or blank if no known threat |
Command Example
!umbrella-domain-security domain=cnn.com
Context Example
Domain:{} 2 items
Name:cnn.com
Security:{} 13 items
PrefixScore:-0.008968782766875304
Geoscore:0
Perplexity:0.13991232622025684
Securerank:86.6441456065165
Entropy:0.9182958340544894
AttackName:
ThreatType:
Popularity:100
ASNScore:-0.009098667373339567
RIPScore:0
Pagerank:40.99643
KolmogorovSmirnovTest:0
DGA:0
Human Readable Output
5. Query the DNS database for domains
The DNS database can be used to query the history that Umbrella has seen for a given domain. The most common use case is to obtain the RRs (Resource Record) history for a given domain, passing in the record query type as a parameter, to help build intelligence around an domain.
Base Command
umbrella-domain-dns-history
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | Domain name (e.g., www.cnn.com) | Required |
Context Output
| Path | Description |
|---|---|
| Domain.Address | IP address |
| Domain.DNSHistory.Age | The day in days between now and the last request for this domain. This value is only useful if present |
| Domain.DNSHistory.TtlsMin | Minimum amount of time set that DNS records should be cached |
| Domain.DNSHistory.TtlsMax | Maximum amount of time set that DNS records should be cached |
| Domain.DNSHistory.TtlsMean | Average amount of time set that DNS records should be cached |
| Domain.DNSHistory.TtlsMedian | Median amount of time set that DNS records should be cached |
| Domain.DNSHistory.TtlsStddev | Standard deviation of the amount of time set that DNS records should be cached |
| Domain.DNSHistory.CountryCodes | List of country codes (ex: US, FR, TW) for the IPs the name maps to |
| Domain.DNSHistory.CountryCount | Number of countries the IPs are hosted in |
| Domain.DNSHistory.Asns | List of ASN numbers the IPs are in |
| Domain.DNSHistory.AsnsCount | Number of ASNs the IPs map to |
| Domain.DNSHistory.Prefixes | List of network prefixes the IPs map to |
| Domain.DNSHistory.PrefixesCount | Number of network prefixes the IPs map to |
| Domain.DNSHistory.Rips | Number of IPs seen for the domain name |
| Domain.DNSHistory.DivRips | The number of prefixes over the number of IPs |
| Domain.DNSHistory.Locations | List of geo coordinates (WGS84 datum, decimal format) the IPs are mapping to |
| Domain.DNSHistory.LocationsCount | Number of distinct geo coordinates the IPs are mapping to |
| Domain.DNSHistory.GeoDistanceSum | Minimum sum of distance between locations, in kilometers |
| Domain.DNSHistory.GeoDistancMean | Mean distance between the geo median and each location, in kilometers |
| Domain.DNSHistory.MailExchanger | Boolean, If an MX query for this domain name has been seen |
| Domain.DNSHistory.NonRoutable | Boolean. If one of the IPs is in a reserved, non-routable IP range |
| Domain.DNSHistory.FfCandidate | Boolean. If the domain name looks like a candidate for fast flux. This does not necessarily mean the domain is in fast flux, but rather that the IP address the domain resolves to changes rapidly |
| Domain.DNSHistory.RipsStability | 1.0 divided by the number of times the set of IP addresses changed |
| Domain.DNSHistory.BaseDomain | The base domain of the requested domain |
| Domain.DNSHistory.IsSubdomain | Boolean. True if the requested domain is a subdomain of another |
Command Example
!umbrella-domain-dns-history domain=cnn.com
Context Example
Domain:{} 2 items
DNSHistory:{} 26 items
Prefixes:[] 1 item
0:151.101.0.0
FfCandidate:false
NonRoutable:false
GeoDistanceSum:0
Ip:151.101.1.67
TtlsMin:60
DivRips:0.25
GeoDistanceMean:0
TtlsMean:60
Cname:false
PrefixesCount:1
RipsStability:1
CountryCodes:[] 1 item
0:US
TtlsMedian:60
LocationsCount:1
BaseDomain:cnn.com
Asns:[] 1 item
0:54113
AsnsCount:1
MailExchanger:true
TtlsStddev:0
CountryCount:1
IsSubdomain:false
Rips:4
TtlsMax:60
Locations:[] 1 item
0:{} 2 items
lat:37.76969909667969
lon:-122.39329528808594
Age:92
Name:cnn.com
Human Readable Output
6. Query the DNS database for IPs
The DNS database can be used to query the history that Umbrella has seen for a given IP address. The most common use case is to obtain the DNS Resource Record (RR) history for a given IP, passing in the record query type as a parameter, to help build intelligence around an IP or a range of IPs. The information provided is from within the last 90 days.
Base Command
umbrella-ip-dns-history
Input
| Argument Name | Description | Required |
|---|---|---|
| ip | IP address | Required |
Context Output
| Path | Description |
|---|---|
| IP.Address | IP address |
| IP.DNSHistory.RRS.Name | The looked-up IP address |
| IP.DNSHistory.RRS.Class | DNS class type |
| IP.DNSHistory.RRS.Type | Query type |
| IP.DNSHistory.RRS.RR | Resource record owner |
| IP.DNSHistory.RRS.TTL | Time to live for this record |
| IP.DNSHistory.Feature.RrCount | Number of records of that type mapping to the given IP |
| IP.DNSHistory.Feature.Ld2Count | Number of 2-level names mapping to the given IP |
| IP.DNSHistory.Feature.Ld3Count | Number of 3-level names mapping to the given IP |
| IP.DNSHistory.Feature.Ld21Count | Number of 2-level names, without the TLD, mapping to the given IP |
| IP.DNSHistory.Feature.Ld22Count | Number of 3-level names, without the TLD, mapping to the given IP |
| IP.DNSHistory.Feature.DivLd2 | ld2_count divided by the number of records |
| IP.DNSHistory.Feature.DivLd3 | ld3_count divided by the number of records |
| IP.DNSHistory.Feature.DivLd21 | ld2_1_count divided by the number of records |
| IP.DNSHistory.Feature.DivLd22 | ld2_2_count divided by the number of records |
Command Example
!umbrella-ip-dns-history ip=1.2.3.99
Context Example
IP:{} 2 items
Address:1.2.3.99
DNSHistory:{} 2 items
Features:{} 9 items
DivLd21:1
DivLd22:1
DivLd2:1
DivLd3:1
RrCount:2
Ld3Count:2
Ld2Count:2
Ld22Count:2
Ld21Count:2
RRS:[] 2 items
0:{} 5 items
Class:IN
Name:1.2.3.99
RR:dnstest-099.brightsignnetwork.com.
TTL:1800
Type:A
1:{} 5 items
Class:IN
Name:1.2.3.99
RR:jp.rogers.com.
TTL:86400
Type:A
Human Readable Output
7. Get malicious domains associated with an IP address
Determines whether the specified IP address has any known malicious domains associated with it. The domains that display when using this endpoint are those that currently exist in the Umbrella block list. This endpoint will return an array with a single domain name for each domain associated with the IP, along with an ID number, which you can ignore.
Base Command
umbrella-ip-malicious-domains
Input
| Argument Name | Description | Required |
|---|---|---|
| ip | IP address | Required |
Context Output
| Path | Description |
|---|---|
| Domain.Name | Domain name |
| Domain.Malicious.Vendor | For malicious domains, the vendor that made the decision |
| Domain.Malicious.Description | For malicious domains, the reason for the vendor to make the decision |
| DBotScore.Indicator | The Indicator |
| DBotScore.Vendor | The DBot score vendor |
| DBotScore.Type | The Indicator type |
| DBotScore.Score | The DBot score |
Command Example
!umbrella-ip-malicious-domains ip=1.2.3.4
Context Example
Domain:{} 2 items
Malicious:{} 2 items
Description:For IP 1.2.3.4
Vendor:Cisco Umbrella
Name:summaryorder-qpc.serveftp.com
Human Readable Output
8. Get a list of domains that match a regular expression (regex)
Returns a list of domains that match a a regular expression. You can use this for domain squatting. The pattern search functionality in Investigate uses regular expressions (regex) to search against the Investigate database. For more information on regex, see online tools, such as http://regexr.com .
Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.
Base Command
umbrella-domain-search
Input
| Argument Name | Description | Required |
|---|---|---|
| regex | Enter a domain regular expression (e.g. "cn.*\\.com"). Note to use double backslash ("\\") | Required |
| start | Example: -2weeks, -1 day, -1000minutes, EPOCH unix time, MAX: -31days | Optional |
Context Output
| Path | Description |
|---|---|
| Domain.Name | Domain name |
| Domain.FirstSeen | First seen time in Epoch format |
| Domain.FirstSeenISO | First seen time in ISO format |
| Domain. SecurityCategories | Matching Umbrella Security Categories |
Command Example
!umbrella-domain-search regex=googlem.*.com start=-1days
Context Example
Domain:{} 4 items
FirstSeen:1535363700000
FirstSeenISO:2018-08-27T09:55:00.000Z
Name:googlemail.top-office.com
SecurityCategories:null
Human Readable Output
9. Get the reputation for a domain
Get Domain Reputation info using Cisco Umbrella Investigate.
Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.
Base Command
domain
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to categorize, supports comma-separated lists (e.g., www.amazon.com,www.facebook.com,www.yahoo.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Domain.Name | string | Domain name |
| Domain.Umbrella.RiskScore | number | The status will be "-1" if the domain is believed to be malicious, "1" if the domain is believed to be benign, "0" if it hasn't been classified yet. |
| Domain.Umbrella.SecureRank | number | Suspicious rank for a domain that reviews based on the lookup behavior of client IP for the domain. Securerank is designed to identify hostnames requested by known infected clients but never requested by clean clients, assuming these domains are more likely to be bad. Scores returned range from -100 (suspicious) to 100 (benign). |
| Domain.Umbrella.FirstQueriedTime | number | The time when the attribution for this Domain was made. |
| DBotScore.Indicator | string | The Indicator |
| DBotScore.Score | number | The DBot score |
| DBotScore.Type | string | The Indicator type |
| DBotScore.Vendor | string | The DBot score vendor |
| Domain.Umbrella.ContentCategories | string | The Umbrella content category or categories that match this domain. If none of them match, the return will be blank. |
| Domain.Umbrella.MalwareCategories | string | The Umbrella security category, or categories, that match this domain or that this domain is associated with. If none match, the return will be blank. |
| Domain.Malicious.Vendor | string | For malicious domains, the vendor that made the decision |
| Domain.Malicious.Description | string | For malicious domains, the reason for the vendor to make the decision |
| Domain.Admin.Country | string | The country of the domain administrator. |
| Domain.Admin.Email | string | The email address of the domain administrator. |
| Domain.Admin.Name | string | The name of the domain administrator. |
| Domain.Admin.Phone | string | The phone number of the domain administrator. |
| Domain.Registrant.Country | string | The country of the registrant. |
| Domain.Registrant.Email | string | The email address of the registrant. |
| Domain.Registrant.Name | string | The name of the registrant. |
| Domain.Registrant.Phone | string | The phone number of the registrant. |
| Domain.CreationDate | date | The date on which the domain was created. |
| Domain.DomainStatus | string | The status of the domain. |
| Domain.UpdatedDate | date | The date on which the domain was last updated. |
| Domain.ExpirationDate | date | The expiration date of the domain. |
| Domain.Registrar.Name | string | The name of the registrar, such as "GoDaddy". |
Command Example
!domain domain=cnn.com using-brand="Cisco Umbrella Investigate - Python"
Context Example
DBotScore:{} 4 items
Indicator:cnn.com
Score:1
Type:Domain
Vendor:Cisco Umbrella
Domain:{} 2 items
Name:cnn.com
Umbrella:{} 5 items
ContentCategories:[] 1 item
0:News/Media
FirstQueriedTime:1993-09-22
MalwareCategories:[] 0 items
RiskScore:1
SecureRank:86.5019890432578
Human Readable Output
10. Get a list of domain names requested the same time as a specified domain and a list of co-occurences
Returns a list of domain names that are frequently seen requested around the same time as the specified domain name (up to 60 seconds before or after), and a list of co-occurences.
Base Command
umbrella-get-related-domains
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to see related domains for (e.g., www.cnn.com) | Required |
| coOccurences | Set to true to get a list of co-occurences. (A co-occurrence is when two or more domains are being accessed by the same users within a small window of time) By default, this value will be false. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.RelatedDomains.Domain | string | Domain name |
| Umbrella.RelatedDomains.Data.Name | string | Domain names that have been frequently seen requested around the same time (up to 60 seconds before or after) as the given domain name. |
| Umbrella.CoOccurences.Data.Name | string | All co-occurences of requests from client IPs are returned for the previous seven days whether the co-occurence is suspicious or not. |
| Umbrella.CoOccurences.Data.Score | number | The values range between 0 and 1 and should not exceed 1. |
| Umbrella.RelatedDomains.Data.Score | number | The score here is the number of client IP requests to the site around the same time as the site being looked up. This is a score reflecting the number of client IPs looking up related sites within 60 seconds of the original request |
| Umbrella.CoOccurences.Domain | string | The domain's name. |
Command Example
!umbrella-get-related-domains domain=walla.com coOccurences=true
Context Example
Umbrella:{} 2 items
CoOccurences:{} 2 items
Data:[] 3 items
0:{} 2 items
Name:rgmkt.net
Score:0.9783944034610161
1:{} 2 items
Name:ns43.domaincontrol.com
Score:0.013178370929884454
2:{} 2 items
Name:ns44.domaincontrol.com
Score:0.008427225609099349
Domain:walla.com
RelatedDomains:{} 2 items
Data:[] 2 items
0:{} 2 items
Name:c3s2.iphmx.com
Score:4
1:{} 2 items
Name:rgmkt.net
Score:3
Domain:walla.com
Human Readable Output
11. List all classifiers for a domain
List all the classifiers used for a particular domain to assign a particular security categorization or threat type (indicators of compromise).
Base Command
umbrella-get-domain-classifiers
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to see classifiers for (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.DomainClassifiers.Domain | string | Domain name |
| Umbrella.DomainClassifiers.Data.MalwareCategories | string | Which Umbrella security category, if any, matched the input |
| Umbrella.DomainClassifiers.Data.AttackNames | string | Which named attacks, if any, matched the input |
| Umbrella.DomainClassifiers.Data.ThreatTypes | string | Which threat type, if any, matched in the input. |
Command Example
!umbrella-get-domain-classifiers domain=cosmos.furnipict.com
Context Example
Umbrella:{} 1 item
DomainClassifiers:{} 2 items
Data:{} 3 items
Attacks:[] 1 item
0:Neutrino
SecurityCategories:[] 1 item
0:Malware
ThreatTypes:[] 1 item
0:Exploit Kit
Domain:cosmos.furnipict.com
Human Readable Output
12. Get the number of DNS queries for a domain
Returns the number of DNS queries made per hour to the specified domain by users of Umbrella's recursive DNS servers.
Base Command
umbrella-get-domain-queryvolume
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to see the volume for (e.g., www.cnn.com) | Required |
| start | Point in time in the past, expressed as a timestamp in the following format or relative time. Valid formats: start=-2days start=-2hours start=1997-07-16T19:20:30+01:00 i.e YYYY-MM-DDThh:mm:ssTZD Note the negative sign. The max is 30 days. | Required |
| stop | Point in time in the past expressed as a timestamp in milliseconds or relative time. Also valid is 'now'. Valid formats: stop=-1days stop=now start=1997-07-16T19:20:30+01:00 i.e YYYY-MM-DDThh:mm:ssTZD Note the negative sign. The max is 30 days. | Required |
| match | Valid options are: exact, component, or all (default). Â Â 1.Using "cisco.com" as an example, "exact" only gives results for cisco.com. Â Â 2. Component gives results for every component of cisco.com, but not cisco.com. Examples are www.cisco.com , mail.cisco.com, wwwin.cisco.com, something.else.cisco.com. 3.All returns the sum of component and exact, this is the default. | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.QueryVolume.Domain | string | Domain name |
| Umbrella.QueryVolume.Data.StartDate | string | Start date for which the volume data is returned. |
| Umbrella.QueryVolume.Data.StopDate | string | Stop date for which the volume data is returned. |
| Umbrella.QueryVolume.Data.QueriesInfo.QueryHour | string | Query hour for which the queries data is returned. |
| Umbrella.QueryVolume.Data.QueriesInfo.Queries | string | Number of DNS queries per hour, in ascending order, to the specified domain. |
Command Example
!umbrella-get-domain-queryvolume domain=walla.com match=all start=-6hours
Context Example
Umbrella:{} 1 item
QueryVolume:{} 2 items
Data:{} 3 items
QueriesInfo:[] 7 items
0:{} 2 items
Queries:3021
QueryHour:2018-10-14T06:00:00
1:{} 2 items
Queries:2924
QueryHour:2018-10-14T07:00:00
2:{} 2 items
Queries:3086
QueryHour:2018-10-14T08:00:00
3:{} 2 items
Queries:3189
QueryHour:2018-10-14T09:00:00
4:{} 2 items
Queries:3068
QueryHour:2018-10-14T10:00:00
5:{} 2 items
Queries:0
QueryHour:2018-10-14T11:00:00
6:{} 2 items
Queries:0
QueryHour:2018-10-14T12:00:00
StartDate:2018-10-14T06:00:00
StopDate:2018-10-14T12:00:00
Domain:walla.com
Human Readable Output
13. Get domain security data
The security information API method contains multiple scores or security features, which can act as relevant datapoints to build insight on the reputation.
Base Command
umbrella-get-domain-details
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to see security information for (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.DomainDetails.Domain | string | Domain name |
| Umbrella.DomainDetails.Data.DGA | string | Domain Generation Algorithm. This score is generated based on the likeliness of the domain name being generated by an algorithm rather than a human. This score ranges from -100 (suspicious) to 0 (benign). |
| Umbrella.DomainDetails.Data.Entropy | number | The number of bits required to encode the domain name, as a score. This score is to be used in conjunction with DGA and Perplexity. |
| Umbrella.DomainDetails.Data.SecureRank | number | Suspicious rank for a domain that reviews based on the lookup behavior of client IP for the domain. Securerank is designed to identify hostnames requested by known infected clients but never requested by clean clients, assuming these domains are more likely to be bad. Scores returned range from -100 (suspicious) to 100 (benign). |
| Umbrella.DomainDetails.Data.PrefixScore | number | Prefix ranks domains given their IP prefixes (an IP prefix is the first three octets in an IP address) and the reputation score of these prefixes. Ranges from -100 to 0, -100 being very suspicious. |
| Umbrella.DomainDetails.Data.RipScore | number | RIP ranks domains given their IP addresses and the reputation score of these IP addresses. Ranges from -100 to 0, -100 being very suspicious. |
| Umbrella.DomainDetails.Data.Popularity | number | The number of unique client IPs visiting this site, relative to the all requests to all sites. A score of how many different client/unique IPs go to this domain compared to others. |
| Umbrella.DomainDetails.Data.Geodiversity | number | A score representing the number of queries from clients visiting the domain, broken down by country. Score is a non-normalized ratio between 0 and 1. |
| Umbrella.DomainDetails.Data.TldGeodiversity | number | A score that represents the TLD country code geodiversity as a percentage of clients visiting the domain. Occurs most often with domains that have a ccTLD. Score is normalized ratio between 0 and 1. |
| Umbrella.DomainDetails.Data.KolmogorovSmirnovTest | number | Kolmogorov–Smirnov test on geodiversity. 0 means that the client traffic matches what is expected for this TLD. |
| DBotScore.Indicator | string | The Indicator |
| DBotScore.Score | number | The DBot score |
| DBotScore.Type | string | The Indicator type |
| DBotScore.Vendor | string | The DBot score vendor |
| Domain.Malicious.Vendor | string | For malicious domains, the vendor that made the decision |
| Domain.Malicious.Description | string | For malicious domains, the reason for the vendor to make the decision |
Command Example
!umbrella-get-domain-details domain=cnn.com
Context Example
DBotScore:{} 4 items
Indicator:cnn.com
Score:1
Type:Domain
Vendor:Cisco Umbrella
Umbrella:{} 1 item
DomainDetails:{} 2 items
Data:{} 13 items
PrefixScore:-0.01103978469603726
Geoscore:0
Perplexity:0.13991232622025684
Securerank:86.5019890432578
Entropy:0.9182958340544894
AttackName:
ThreatType:
Popularity:100
ASNScore:-0.033617132988484844
RIPScore:0
Pagerank:39.26072
KolmogorovSmirnovTest:0
DGA:0
Domain:cnn.com
Human Readable Output
14. Get domains associated with registrar email addresses
Returns the domains associated with the email addresses of the registrar that are looked up.
Base Command
umbrella-get-domains-for-email-registrar
Input
| Argument Name | Description | Required |
|---|---|---|
| emails | Email address following rfc5322 conventions. (e.g. : admin@google.com ) Comma separated list allowed. (e.g. : admin@google.com , dns-admin@google.com , hostmaster@charter.com ) | Required |
| offset | For paging with offset for domains with more than 500 results, set the url-param limit. Default value is 10. | Optional |
| sort | To sort the list of domains based on timestamp. By default, domains are simply sorted by name in alphabetical order. Possible values are: ""created"", ""updated"", and ""expired"", each of which sorts from the most recent date for the value of the WHOIS entry. | Optional |
| limit | To limit the total number of results (domains). | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.AssociatedDomains.Email | string | Email address |
| Umbrella.AssociatedDomains.Data.TotalResults | number | Total number of results for this email. |
| Umbrella.AssociatedDomains.Data.MoreDataAvailable | boolean | Whether or not there are more than 500 results for this email, either yes or no. |
| Umbrella.AssociatedDomains.Data.ResultLimit | number | Total number of results for this page of results, default 500. |
| Umbrella.AssociatedDomains.Data.Domains.Name | string | Domains registered by this email |
| Umbrella.AssociatedDomains.Data.Domains.Name.SecurityCategories | string | Security Categories associated with the domain. |
| Umbrella.AssociatedDomains.Data.Domains.Name.ContentCategories | string | Content Categories associated with the domain. |
| Umbrella.AssociatedDomains.Data.Domains.LastObserved | string | Whether the domain is current, meaning currently registered by this email address. Values : Past or Current |
Command Example
!umbrella-get-domains-for-email-registrar emails=dns@google.com
Context Example
Umbrella:{} 1 item
AssociatedDomains:{} 2 items
Data:[] 1 item
0:{} 4 items
Domains:[] 2 items
0:{} 4 items
Content Categories:[] 0 items
Is Current:true
Name:careersgoogle.com
Security Categories:[] 0 items
1:{} 4 items
Content Categories:[] 0 items
Is Current:true
Name:chronweb.com
Security Categories:[] 0 items
MoreDataAvailable:false
ResultLimit:500
TotalResults:2
Email:
dns@google.com
Human Readable Output
15. Get all domains for a nameserver
Get all domains registered by a specified nameserver. In a query, you can search against a single nameserver or multiple nameservers.
Base Command
umbrella-get-domains-for-nameserver
Input
| Argument Name | Description | Required |
|---|---|---|
| nameservers | Domain name of the Nameserver (e.g., ns2.google.com) Comma separated list allowed. (e.g. : ns2.google.com, ns1.google.com) | Required |
| offset | For paging with offset for domains with more than 500 results, set the url-param limit. Default value is 10. | Optional |
| sort | "To sort the list of domains based on timestamp. By default, domains are simply sorted by name in alphabetical order. Possible values are: ""created"", ""updated"", and ""expired"", each of which sorts from the most recent date for the value of the WHOIS entry." | Optional |
| limit | To limit the total number of results (domains). | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.AssociatedDomains.Nameserver | string | Nameserver's domain name. |
| Umbrella.AssociatedDomains.Data.TotalResults | string | Total number of results for this nameserver domain name. |
| Umbrella.AssociatedDomains.Data.MoreDataAvailable | boolean | Whether or not there are more than 500 results for this email, either yes or no. |
| Umbrella.AssociatedDomains.Data.ResultLimit | number | Total number of results for this page of results, default 500. |
| Umbrella.AssociatedDomains.Data.Domains.Name | string | Domains registered by this nameserver. |
| Umbrella.AssociatedDomains.Data.Domains.Name.SecurityCategories | string | Security Categories associated with the domain. |
| Umbrella.AssociatedDomains.Data.Domains.Name.ContentCategories | string | Content Categories associated with the domain. |
| Umbrella.AssociatedDomains.Data.Domains.LastObserved | string | Whether the domain is current, meaning currently registered by this email address. Values : Past or Current |
Command Example
!umbrella-get-domains-for-nameserver nameservers=ns1.google.com limit=2
Context Example
Umbrella:{} 1 item
AssociatedDomains:{} 2 items
Data:[] 1 item
0:{} 4 items
Domains:[] 2 items
0:{} 4 items
Content Categories:[] 0 items
Is Current:false
Name:googlerightsflow.net
Security Categories:[] 0 items
1:{} 4 items
Content Categories:[] 0 items
Is Current:true
Name:mycloudaudit.net
Security Categories:[] 0 items
MoreDataAvailable:true
ResultLimit:2
TotalResults:2
Nameserver:ns1.google.com
Human Readable Output
16. Get WHOIS data for a domain
Return a standard WHOIS response record for a single domain with all available WHOIS data returned.
Base Command
umbrella-get-whois-for-domain
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | Domain name, including TLD, and excluding wildcards (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.WHOIS.Domain | string | Domain name |
| Umbrella.WHOIS.Data.RegistrarName | string | Domain registrar name |
| Umbrella.WHOIS.Data.LastRetrieved | string | Domain last retrieved date |
| Umbrella.WHOIS.Data.Created | string | Domain created date |
| Umbrella.WHOIS.Data.Updated | string | Domain updated date |
| Umbrella.WHOIS.Data.Expires | string | Domain expiry date |
| Umbrella.WHOIS.Data.IANAID | string | IANA ID |
| Umbrella.WHOIS.Data.LastObserved | string | Domain last observed |
| Umbrella.WHOIS.Data.Nameservers.Name | string | Domain's name servers |
| Umbrella.WHOIS.Data.Emails.Name | string | Domain's email |
| Domain.Admin.Country | string | The country of the domain administrator. |
| Domain.Admin.Email | string | The email address of the domain administrator. |
| Domain.Admin.Name | string | The name of the domain administrator. |
| Domain.Admin.Phone | string | The phone number of the domain administrator. |
| Domain.Registrant.Country | string | The country of the registrant. |
| Domain.Registrant.Email | string | The email address of the registrant. |
| Domain.Registrant.Name | string | The name of the registrant. |
| Domain.Registrant.Phone | string | The phone number of the registrant. |
| Domain.CreationDate | date | The date on which the domain was created. |
| Domain.DomainStatus | string | The status of the domain. |
| Domain.UpdatedDate | date | The date on which the domain was last updated. |
| Domain.ExpirationDate | date | The expiration date of the domain. |
| Domain.Registrar.Name | string | The name of the registrar, such as "GoDaddy". |
Command Example
!umbrella-get-whois-for-domain domain=cnn.com
Context Example
Umbrella:{} 1 item
WHOIS:{} 2 items
Data:{} 10 items
Nameservers:[] 4 items
0:ns-1086.awsdns-07.org
1:ns-1630.awsdns-11.co.uk
2:ns-47.awsdns-05.com
3:ns-576.awsdns-08.net
IANAID:299
Created:1993-09-22
Name:cnn.com
LastRetrieved:1537481654499
Expires:2026-09-21
Emails:[] 2 items
0:
example.gmail.com
1:
example.gmail.com
RegistrarName:CSC CORPORATE DOMAINS, INC.
Updated:2018-04-10
LastObserved:2018-09-20 16:53:49.000 UTC
Domain:cnn.com
Human Readable Output
17. Get malicious domains associated with an IP address
Returns a list of malicious domains associated with the specified IP address.
Base Command
umbrella-get-malicious-domains-for-ip
Input
| Argument Name | Description | Required |
|---|---|---|
| ip | IP address to check for malicious domains | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.MaliciousDomains.IP | string | IP address |
| Umbrella.MaliciousDomains.Data.Name | string | The block list domain associated with the IP |
| Umbrella.MaliciousDomains.Data.LastObserved | string | Whether the domain is current, meaning currently registered by this email address (Values: Past or Current ) |
| Umbrella.MaliciousDomains.Data.MalwareCategories | string | Security categories associated with the domain. |
| Umbrella.MaliciousDomains.Data.ContentCategories | string | Content categories associated with the domain |
Command Example
!umbrella-get-malicious-domains-for-ip ip=8.8.8.8
Context Example
DBotScore:[] 52 items
0:{} 4 items
Indicator:bo1aa21.com
Score:3
Type:Domain
Vendor:Cisco Umbrella
1:{} 4 items
Indicator:z015.mypsx.net
Score:3
Type:Domain
Vendor:Cisco Umbrella
Domain:[] 52 items
0:{} 2 items
Malicious:{} 2 items
Description:For IP 8.8.8.8
Vendor:Cisco Umbrella
Name:bo1aa21.com
1:{} 2 items
Malicious:{} 2 items
Description:For IP 8.8.8.8
Vendor:Cisco Umbrella
Name:z015.mypsx.net
Umbrella:{} 1 item
MaliciousDomains:{} 2 items
Data:[] 52 items
0:{} 3 items
ContentCategories:[] 0 items
MalwareCategories:[] 1 item
0:Command and Control
Name:bo1aa21.com
1:{} 3 items
ContentCategories:[] 1 item
0:Infrastructure
MalwareCategories:[] 1 item
0:Malware
Name:z015.mypsx.net
Human Readable Output
18. Get a list of domains that match a regular expression (regex)
Get a list of domains that match a regular expression (regex).
Base Command
umbrella-get-domains-using-regex
Input
| Argument Name | Description | Required |
|---|---|---|
| expression | A standard RegEx search pattern, must be encoded in a double quoted bracket. | Required |
| start | Can either be specified in relative or absolute time. Point in time in the past, expressed as a timestamp in the following format or relative time. Valid formats: start=-2days start=-2hours start=-1000minutes start=-3weeks start=1997-07-16T19:20:30+01:00 i.e YYYY-MM-DDThh:mm:ssTZD Note the negative sign for relative time. Max is -30days. | Required |
| includeCategory | Default is false, if set to true this will include security categories in the results and may slow the return times. | Optional |
| stop | The exclusive end time in milliseconds absolute or relative time (eg: 'now', '-2days','1997-07-16T19:20:30+01:00') for a query. | Optional |
| limit | The maximum number of items to return - combine with offset for result pagination | Optional |
| type | Search database node type (URL, IP, HOST). | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.DomainSearch.TotalResults | number | Total results from this search string. The default number of results is 100 and can be expanded using the limit parameter. |
| Umbrella.DomainSearch.Data.Name | string | Name of the domain found |
| Umbrella.DomainSearch.Data.FirstSeen | string | Date the first time the domain was first seen |
Command Example
!umbrella-get-domains-using-regex expression=googleapis.*.com limit=2
Context Example
Umbrella:{} 1 item
DomainSearch:{} 3 items
Data:[] 2 items
0:{} 2 items
FirstSeen:1539042240000
Name:googleapis.com.nauticaintegral.com
1:{} 2 items
FirstSeen:1539244920000
Name:googleapis.com.sanpada.com
Expression:googleapis.*.com
TotalResults:2
Human Readable Output
19. Query when a domain was attributed to a security category or as a threat type
Shows when a domain was attributed to a particular security categorization or threat type (indicators of compromise).
Base Command
umbrella-get-domain-timeline
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name to see the timeline for (e.g., www.cnn.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.Timeline.Domain | string | Domain name |
| Umbrella.Timeline.Data.MalwareCategories | string | Which Umbrella security category, if any, matched the input |
| Umbrella.Timeline.Data.Attacks | string | Which named attacks, if any, matched the input |
| Umbrella.Timeline.Data.ThreatTypes | string | Which threat type, if any, matched in the input. |
| Umbrella.Timeline.Data.Timestamp | string | The time when the attribution for this Domain changed. |
Command Example
!umbrella-get-domain-timeline domain=cosmos.furnipict.com
Context Example
Umbrella:{} 1 item
Timeline:{} 2 items
Data:[] 4 items
0:{} 4 items
Attacks:[] 1 item
0:Neutrino
MalwareCategories:[] 1 item
0:Malware
ThreatTypes:[] 1 item
0:Exploit Kit
Timestamp:2017-10-21T19:30:33
1:{} 4 items
Attacks:[] 1 item
0:Neutrino
MalwareCategories:[] 2 items
0:Dynamic DNS
1:Malware
ThreatTypes:[] 1 item
0:Exploit Kit
Timestamp:2016-10-21T17:22:03
2:{} 4 items
Attacks:[] 1 item
0:Neutrino
MalwareCategories:[] 1 item
0:Malware
ThreatTypes:[] 1 item
0:Exploit Kit
Timestamp:2016-07-11T18:12:06
3:{} 4 items
Attacks:[] 0 items
MalwareCategories:[] 0 items
ThreatTypes:[] 0 items
Timestamp:2016-07-09T03:49:08
Domain:cosmos.furnipict.com
Human Readable Output
20. Query when an IP address was attributed to a security organization or as a threat type
Shows when an IP was attributed to a particular security categorization or threat type (indicators of compromise).
Base Command
umbrella-get-ip-timeline
Input
| Argument Name | Description | Required |
|---|---|---|
| ip | The IP to see the timeline for (e.g., 8.8.8.8) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.Timeline.IP | string | IP address |
| Umbrella.Timeline.Data.MalwareCategories | string | Which Umbrella security category, if any, matched the input |
| Umbrella.Timeline.Data.Attacks | string | Which named attacks, if any, matched the inputWhich threat type, if any, matched in the input. |
| Umbrella.Timeline.Data.ThreatTypes | string | Which threat type, if any, matched in the input. |
| Umbrella.Timeline.Data.Timestamp | string | The time when the attribution for this IP changed. |
Command Example
!umbrella-get-ip-timeline ip=1.2.3.4
Context Example
Umbrella:{} 1 item
Timeline:{} 2 items
Data:[] 1 item
0:{} 4 items
Attacks:[] 0 items
MalwareCategories:[] 0 items
ThreatTypes:[] 0 items
Timestamp:2018-05-31T20:48:59
IP:1.2.3.4
Human Readable Output
21. Query when a URL was attributed to a security organization or as a threat type
Shows when a URL was attributed to a particular security categorization or threat type (indicators of compromise).
Base Command
umbrella-get-url-timeline
Input
| Argument Name | Description | Required |
|---|---|---|
| url | The URL to see the timeline for (e.g., www.aws.amazon.com) | Required |
Context Output
| Path | Type | Description |
|---|---|---|
| Umbrella.Timeline.URL | string | URL value |
| Umbrella.Timeline.Data.MalwareCategories | string | Umbrella security category that matches the the URL |
| Umbrella.Timeline.Data.Attacks | string | Which named attacks, if any, matched the input |
| Umbrella.Timeline.Data.ThreatTypes | string | Which threat type, if any, matched in the input. |
| Umbrella.Timeline.Data.Timestamp | date | The time when the attribution for this URL changed. |
Command Example
!umbrella-get-url-timeline url=httpx://gauttam.com/wp-includes/
Context Example
Umbrella:{} 1 item
Timeline:{} 2 items
Data:[] 1 item
0:{} 4 items
Attacks:[] 0 items
MalwareCategories:[] 1 item
0:Malware
ThreatTypes:[] 0 items
Timestamp:2018-08-21T13:21:55
URL:httpx://gauttam.com/wp-includes/
Human Readable Output
