Cisco Umbrella Investigate

Use the Cisco Umbrella integration to manage online threats.

Configure Cisco Umbrella Investigate - Python on Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Cisco Umbrella Investigate - Python.
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • Cisco Umbrella API token
    • Use system proxy settings
    • Trust any certificate (not secure)
    • Base URL
    • DBot Score Malicious Threshold
  4. 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 Demisto 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.

  1. Get a domain category: umbrella-domain-categorization/investigate-umbrella-domain-categorization
  2. Get co-occurences for a domain: umbrella-domain-co-occurrences/investigate-umbrella-domain-co-occurrences
  3. Get a list of domain names requested the same time as a specified domain: umbrella-domain-related/investigate-umbrella-domain-related
  4. Get domain security data: umbrella-domain-security/investigate-umbrella-domain-security
  5. Query the DNS database for domains: umbrella-domain-dns-history/investigate-umbrella-domain-dns-history
  6. Query the DNS database for IPs: umbrella-ip-dns-history/investigate-umbrella-ip-dns-history
  7. Get malicious domains associated with an IP address: umbrella-ip-malicious-domains/investigate-umbrella-ip-malicious-domains
  8. Get a list of domains that match a regular expression (regex): umbrella-domain-search/investigate-umbrella-domain-search
  9. Get the reputation for a domain: domain
  10. Get a list of domain names requested the same time as a specified domain and a list of co-occurrences: umbrella-get-related-domains
  11. List all classifiers for a domain: umbrella-get-domain-classifiers
  12. Get the number of DNS queries for a domain: umbrella-get-domain-queryvolume
  13. Get domain security data: umbrella-get-domain-details
  14. Get domains associated with registrar email addresses: umbrella-get-domains-for-email-registrar
  15. Get all domains for a nameserver: umbrella-get-domains-for-nameserver
  16. Get WHOIS data for a domain: umbrella-get-whois-for-domain
  17. Get malicious domains associated with an IP address: umbrella-get-malicious-domains-for-ip
  18. Get a list of domains that match a regular expressions (regex): umbrella-get-domains-using-regex
  19. Query when a domain was attributed to a security organization or as a threat type: umbrella-get-domain-timeline
  20. Query when an IP address was attributed to a security organization or as a threat type: umbrella-get-ip-timeline
  21. 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 .

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

1 investigate-umbrella-domain-categorization

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.

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

2 investigate-umbrella-domain-co-occurrences

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

3 investigate-umbrella-domain-related

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 investigate-umbrella-domain-security

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 investigate-umbrella-domain-dns-history

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 investigate-umbrella-ip-dns-history

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 investigate-umbrella-ip-malicious-domains

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 .

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 investigate-umbrella-domain-search

9. Get the reputation for a domain


Get Domain Reputation info using Cisco Umbrella Investigate.

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

image
image

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

image

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

image

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

image

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

image

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

image

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

image

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

image

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

image

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

image

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

image

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

image

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

image