Programmatically filter uncommon DNS Requests with Cisco Umbrella APIs

We use the Internet in our everyday lives to get work done, manage our lives, and even socialize. We take this Internet usage for granted these days, but the reality is that we are communicating more than ever on a global scale, instantaneously, and often, with folks we’ve never met in-person or with third-party services we don’t fully understand.

From a cybersecurity perspective, this looks like a lot of DNS traffic to have to monitor, understand, and investigate. And, there are increasing reasons to do just that. After the major Colonial Pipeline ransomware attack that resulted in a $4.4 million ransom payment in 2021, the TSA issued (and has since, reissued) a security directive to pipeline utility companies that, in part, asked them to better understand their DNS traffic.

Of course, pipelines are not the only targets of such attacks, meaning we need reasonable methodologies for identifying and investigating potentially malicious domains. In this article, we walk you through how you might programmatically gain visibility into and investigate uncommon DNS requests using Cisco Umbrella APIs.

Initial developer setup

To create this automation, we assume you have an active Cisco Umbrella account with API access, Python3, and an integrated developer environment (IDE) that supports Python.

If you’re not yet an Umbrella user, or you’d simply like to create a proof-of-concept (POC) around this, you can leverage the always-on Umbrella Secure Internet Gateway sandbox through Cisco DevNet.

Defining what traffic is “uncommon”

The day before writing this article, Cisco Umbrella processed over 800 billion DNS requests. As a result of this consistently massive amount of traffic processing and analysis, Umbrella maintains an up to date “Top 1-Million Domains” list as a CSV. This information establishes a baseline of what traffic is common.

We can determine what traffic coming from your Umbrella network is uncommon by comparing it to this Top 1-Million Domains list.

To do this, we make an API call using the Umbrella Reports API to retrieve the Top Destinations seen by your Umbrella network in the past week. The call returns a list of domains from most to least common, one per row, as a CSV, that we can clean to remove the rank order and non-domains. (For example, remove the 8 in this row: 8,www.google.com, and remove IP address destinations because they won’t match an Umbrella Top 1-Million domain)

We can then write logic that compares the domains seen by your network to Umbrella’s Top 1-Million and adds any of your domains that are not on that list to a new CSV.

Sample Code

We’ve written a sample Python script to help you achieve this using your own DNS traffic! That script, along with instructions for running it, can be found at Umbrella Uncommon Domains.

Investigating uncommon domains with Umbrella APIs

Once you’ve identified which domains seen by your network are considered less common, you may choose to further investigate some—or all—of them using Umbrella Investigate.

If you have an Umbrella DNS Security Advantage or Secure Internet Gateway (SIG) package, in the Umbrella dashboard, you can navigate to Investigate > Smart Search and search for the domain you’d like to investigate. You’ll see results that provide information looking something like what you see below for examplemalwaredomain.com:

Umbrella API
Figure 1: The beginning of Umbrella Investigate results for examplemalwaredomain.com

The results first show you both the content and security categories for the domain, provided by Cisco Talos. We can see that this domain is classified as malware and is already on a Malware Block List; though, if we wanted to, we could find additional information on this domain across Talos, Google, or VirusTotal (top right).

Umbrella API
Figure 2: The risk score and security indicators for examplemalwaredomain.com

Scrolling down the results, we next see the risk score assigned to this domain and the security indicators that went into calculating that score. In this case, the domain is classified as High Risk, with additional information on the security indicators here: Investigate Domain Risk Score.

After viewing basic information on the domain, such as when it was created and from what country it originates, as well as associated observables like IP addresses, name servers, and files, you’ll find WHOIS record information on the domain (see below). You’ll notice that Umbrella Investigate allows you to further investigate the associated email address and nameservers.

Umbrella API
Figure 3: WHOIS record data for examplemalwaredomain.com

Finally, we can view a global map showing where DNS requests to examplemalwaredomain.com. In the example map below, over 95% of DNS requests to this domain originate from the United States.

Umbrella API
Figure 4: Global requestor distribution map for examplemalwaredomain.com

These Umbrella Investigate results are also available as part of the Umbrella Investigate API, meaning that the investigation of these uncommon domains can also be done programmatically.

Additional opportunities for automation

What are the possibilities for building upon the automation we’ve provided in the sample code?

  • Investigate – adding logic that for each uncommon domain, an API call is made to the Umbrella Investigate endpoint to retrieve info and any threat intel
  • Ticketing – you could integrate a ticketing system, like Jira, by leveraging its API to create and assign a ticket for each uncommon domain
  • Policy Changes – use the Umbrella Destinations List API to allow or block one or more of the uncommon domains
  • Reporting – export the uncommon domains, and perhaps info on them from Umbrella Investigate, into a more palatable format like PDF. Domain info could also be enhanced by intel from other security products, by viewing associated devices and their relationships with the domain using JupiterOne, and/or used in a visualization.
  • Orchestration – you can orchestration an automation workflow with multiple steps (not all of those steps need be automated) using Cisco XDR. The workflow might include all steps your organization requires for investigation and incident response.
  • Communication – rather than save the resulting CSV of domains locally, you may choose to automatically email the results to interested parties or post the results to a messaging platform like WebEx.



Erika Dietrick

Developer Advocate

Cisco DevNet