The Umbrella Deployment Documentation Developer Hub

Welcome to the Umbrella Deployment Documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Umbrella Deployment Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Enable File Inspection

The Cisco Umbrella File Inspection feature expands the visibility and enforcement capabilities of Umbrella, protecting against more attack vectors for more users. The ability to inspect files is performed in the cloud, not on premises, so there is no need for additional hardware or software to be installed. This document consists of three parts, first outlining how to enable file inspection and how to test it. Then we'll go through viewing reports to see any files that were inspected. Lastly, we'll cover how file inspection actually works in the back-end.

Note: The file inspection feature is only available for customers with the Umbrella Insights or Umbrella Platform packages. For more information about packages, see Umbrella Package Comparison. Contact your Cisco account representative with any questions.

Table of Contents

Features of Umbrella File Inspection

File inspection is an extension of the Umbrella intelligent proxy’s scope and functionality. With this feature enabled, you have the ability to scan files for malicious content hosted on risky domains before those files are downloaded.

A risky domain is neither trusted ("known good") or known to be malicious, but one that could potentially pose a threat because little to no information is known about it.

The file is captured in our proxy, scanned to determine if a threat exists and if so, it's blocked from being downloaded. This can be an explicit download, such as when a user clicks on a link in an email or a download that happens behind the scenes, in so-called 'drive-by download' scenarios. This is reported on in your Umbrella security activity report and the activity search so you can review what was blocked.

The file inspection feature is being rolled out with a few features at a time, essentially we're building it from the ground up, one brick at a time. In this first release of the feature, each file that's inspected is scanned twice. First, it's scanned by an antivirus to determine if it's already known to be malicious and the scanned by Cisco AMP integration, which blocks files with a bad reputations based on checksum.

Enable File Inspection

File inspection can be enabled on a per-policy, per-identity basis but is available for all identities. The intelligent proxy feature is required to be enabled in order to use file inspection, and for new policies, it's enabled by default. We highly recommend enabling SSL Decryption as part of a policy to maximize the benefits of file inspection, although it is not required.

  1. Navigate to Policies > Management > All Policies and click Add or edit an existing policy.
  1. If you're creating a new policy, select the Identities that will use file inspection and then click Next.
  1. When asked what should this policy do, ensure that Inspect Files is selected.

Make sure that the intelligent proxy is enabled. Although not required, we recommend enabling SSL decryption. Adding SSL decryption allows for both types of traffic (secure and insecure) to be proxied and for those files to be inspected. A test scenario with SSL enabled is below.

If you're editing an existing policy, make sure File Inspection is enabled on the summary page after you’ve enabled the Intelligent Proxy (under Advanced Settings).

Cisco Umbrella Root Certificate

The Cisco Umbrella Root Certificate must be installed on all machines with SSL decryption included in their file inspection policy. For more information, see Cisco Certificate Import.

To test SSL decryption with file inspection, use

  1. Click Save.
    If you're testing, ensure that the policy with file inspection enabled in it is at or near the top of the policy list in order that the policy takes precedence.

Test File Inspection

From a device that’s been enrolled in a policy with File Inspection enabled:

  1. Browse to
    Browser to to test the SSL decryption version if enabled in policy.
  2. You should receive a block page like the one below:
  1. The diagnostic information covers a bit of detail about which server the file went through.
  2. Check the reports to ensure it appears as it should. This is covered in the next sections.


If you do not see the block page above, ensure that the policy with File Inspection enabled is higher in the policy order than other policies the enrolled identity(ies) are configured for.

Wait upwards of five minutes before testing again after any policy changes to ensure enough time has passed for the changes to be replicated throughout the Umbrella infrastructure. If problems persist, try clearing the local browser cache on your machine, or even your machine's DNS cache (a reboot will accomplish this).

Beyond that, check to see if you have a local on-prem proxy that is interfering. For more information, see Using Umbrella with an HTTP proxy.

And be sure to that the Cisco Root CA is installed in case of cert errors or files on HTTPS connections not being blocked. For more information, see Cisco Certificate Import Information.

Getting Help

If you encounter any issues with the File Inspection feature, please log a case with Customer Support at:

You may want to include the output of the following commands (these commands should be run from a device enrolled in the policy configured for File Inspection):

dig txt

nslookup -type=txt

You should also include the output of the Umbrella diagnostic to speed up the troubleshooting. See Umbrella Diagnostic Tool.

Reporting for File Inspection

A file that's been inspected and blocked appears in your security logs like any other network event that passes through Umbrella. Both the activity search and the security activity report show file inspection events, but greater detail is found in the security activity report.

Files that were inspected and allowed through because they are safe appear as allowed events in the activity search report without any information about scan results because there is nothing to report.

In the earlier test with, if the test worked as expected you should have a result in your security activity report for the identity that matched when doing test. This can be seen in one of two ways.

Security Activity Report for File Inspection

  1. Navigate to Reporting > Core Reports > Security Activity and using the built-in filters, search for the threat name, which in this example is "EICAR".
  2. Click Advanced Search and filter for threat, then type 'eicar':

The filter should look like this:

The result will appear compressed in a card, as below:

Expand the card by clicking on it and you will see something like the results below. Because every sample of malware is different, each result will vary based on the malware, the identity triggered and which engine detected it as malicious and so on, but the majority of these fields are consistent between various blocks of files that have been inspected.

The SHA-256 hash is especially helpful in cross-referencing between other security data platforms, or even VirusTotal.

Note: The eicar test virus is scanned by both the antivirus engine and the Cisco AMP engine, and detected by both. All files are scanned by both engines and can be detected by both, one or neither. If a sample is detected by both engines, the Cisco AMP detection takes precedence in the reports.



which domain or IP hosted the suspicious file


the URL at which the suspicious file was found at, if available. Usually the same domain as the destination.

Date & Time

when the suspicious file was downloaded by the user and scanned


which Umbrella security categories matched against this event. It is possible for a file to be malicious or suspicious as per the antivirus scanner and Cisco AMP but not be categorized.


either blocked or allowed

User Agent

the user agent of the browser with which the request was made (

Content Type

SHA-256 Hash

checksum of the file, if available. Typically for Cisco AMP; this is also included in the summary.

Status code

the HTTP code returned from the query (typically 300 or 400)


the name found by the antivirus scanner, where applicable


the referrer URL where available/applicable

Security Activity Report for Activity Search

The Activity Search shows files that were allowed through and files that were blocked. Any page on any website could count as a file—files likes .HTML or .CSS are common. In the earlier test to download the test file from, other page elements were downloaded but allowed.

On the far right hand side, the ellipsis icon can be expanded for more information. In this instance, the file was allowed.

Clicking "See Full Details" shows as below (click image to zoom):

The results for Cisco AMP are blank, as the file was allowed.

You can also use the filters for the columns in the activity search to show the 'file name' and make it more apparent. First, select "Columns" and expose the 'File Name' which is hidden by default:

Run the report for the last 24 hours and you'll see the results including the file name that was proxied.

How File Inspection Works

It Starts with the Intelligent Proxy

The first thing to understand about how File Inspection works is to that it employs Umbrella’s intelligent proxy in order to have some domains proxied through our cloud but not others. The intelligent proxy is a cornerstone of how we do advanced protection in the cloud. For more information, see Enable the Intelligent Proxy.

In Umbrella, when identities, such as networks or roaming computers, are pointed to the Umbrella DNS resolvers and when an internet request is made, the first thing that happens is the DNS resolver determines whether a domain is either allowed (safe), blocked or ‘risky.’ If it’s allowed, you’ll get the correct IP address of the domain returned the client. If it’s blocked, the IP of our block page lander is returned. If it’s ‘risky’, the resolver returns the IP of the intelligent proxy. The proxy authenticates the client (using redirects to unique domain) and an allowed URL or file is permitted or blocked.

When it comes to file inspection, the intelligent proxy is the ‘decision maker’ when determining whether a file will be inspected or not. If the intelligent proxy feature is not enabled, it is not possible to use file inspection. In addition, the SSL decryption feature of the intelligent proxy is required in order to scan any files on secure (HTTPS) sites.

How is a File Inspected?

Once a domain deemed 'risky’ is passed to the intelligent proxy, there are internal services within the proxy that handle different parts of the request by breaking the request to the domain into individual pieces. For instance, we can block a single URL of a risky domain and allow other URLs within the same risky domain, based on whether we know that URL is known to be bad.

File inspection works similarly and uses two services to scan. In essence, a file hosted on a website is simply another URL, but for file inspection, we determine what type of file it is and scan it to find out more. The request to the file is made from the proxy and when the file is downloaded to the proxy, the file is then passed to both scanners which analyze the file simultaneously.

It's important to note that files are scanned by both engines but if either engine detects it as being known bad or malicious it's blocked. In the example of the eicar test virus earlier, it's scanned and detected by both the antivirus and Cisco AMP. If both engines detect the file, the AMP detection is given a higher priority in the reporting and it will show up as an AMP event with antivirus information listed in the detail.

Cisco Advanced Malware Protection (AMP) scanning

Cisco AMP is built on an extensive collection of real-time threat intelligence and dynamic malware analytics supplied by the Talos Security Intelligence and Research Group, and Threat Grid intelligence feeds. The Cisco AMP engine does not do real time sandboxing, instead, the Cisco AMP integration blocks files with a known bad reputation based on the checksum or hash of the file. The AMP checksum database is comprised of lookup and data from all AMP customers and is a dynamic global community resource shared between customers utilizing the technology.

Antivirus Scanning

The antivirus scanner attempts to scan all files. We begin streaming large files from the proxy to the user after scanning the first 50mb in order to ensure that the user starts receiving the download while scanning continues in the background. As soon as a file is identified as malicious, the connection is terminated. For larger files, the user may initially experience a brief lag, but should still receive the entire file as quickly as normal—unless it's malicious.

Archives (such as .zip or .rar files) will be decompressed to a maximum of five levels of recursion deep. A password-protected archive is not scanned as it cannot be decompressed without the password, however it will be blocked under the category Protected Archive. If there is a scanning error or the file is found to be corrupt or otherwise encrypted, we are blocking that as well. Since we have determined already that the domain could contain risky files, we're taking the safest options when scanning files from those domains.

Once that scanning is complete, the file is either delivered to the customer or the connection is terminated and the user is served the IP of the block page instead of the file they might have been expecting to see.

Reporting and the Intelligent Proxy < Enable File Inspection > Install the Cisco Certificate

Enable File Inspection

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.