The Umbrella User Guide Developer Hub

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

Get Started    

Enable Threat Grid Malware Analysis

Web policy only

Web Policies Only

Threat Grid Malware Analysis is only available for the Web policy

Threat Grid is Cisco's malware analysis and threat intelligence platform. Threat Grid generates and gathers malware intelligence through static and dynamic runtime sample analysis, as well as from other Cisco integrations. When you enable Umbrella's File Inspection and Threat Grid Malware Analysis features, files not blocked through File Inspection and that are unknown to Advanced Malware Protection (AMP) file reputation or blocked by Umbrella's anti-virus (AV) may be submitted by Umbrella to Threat Grid for malware analysis. This includes file types known to carry malware or be a conduit for malware, such as EXE and PDF files.

Thus, a file not blocked by Umbrella because File Inspection does not detect that the file is malicious can be downloaded when requested; however, with Threat Grid Malware Analysis enabled, an unknown file is also submitted to Threat Grid for further examination. Threat Grid may also sandbox a submitted file so that it can be analyzed in safety to determine whether or not it is malicious. If Threat Grid determines that a file is malicious, Threat Grid sends this information to AMP and Umbrella's File Inspection feature blocks any new attempts to download the file, which is now known to be malicious. While Threat Grid does not protect against the first download of a new or unknown malicious file, it is an important addition to your organization's defenses against threats because it can prevent future downloads. The next device in your organization that attempts a download is now protected. In fact, now that AMP knows about this file, all Umbrella SIG customers with File Inspection enabled are protected.

For more information about Threat Grid, see Cisco Threat Grid.

For more information about AMP, see Advanced Malware Protection (AMP).

Umbrella's Threat Grid Integration

Threat Grid integration with Umbrella is included with Umbrella's secure web gateway (SWG). This integration includes access to a limited version of Threat Grid's dashboard.

When you enable Threat Grid Malware Analysis for the first time, you must choose a sandbox location. Once this location is set, you are sent an email from Threat Grid with credentials information including your login and a link to reset your password, which you must do within 36 hours. You cannot use your Umbrella credentials to log into Threat Grid. Your login credentials to Threat Grid give you limited access to Threat Grid's functionality that allows you to view files submitted to Threat Grid by Umbrella's File Analysis feature. For more information about how to use Threat Grid, see Threat Grid's Help which is available from the Threat Grid dashboard.

When integration is enabled through Umbrella, Threat Grid is limited to examining a maximum of 500 files per 24 hours. As well, there is a file size limitation of 50 Mb. Files over 50 Mb in size are not submitted to Threat Grid. You must log into Threat Grid to monitor the number of files submitted within a 24 hour period. At the end of the rolling 24 hour time period, this quota is cleared and submissions start again—if this hard limit of 500 files is reached; otherwise, submissions continue unabated. To increase this limit of 500 files per 24 hours, contact your account manager.

For multi-org deployments of Umbrella, the rolling limit of 500 files per 24 hours is shared between the parent and child organizations. The limit of 500 files is calculated by combining all child and parent organization submissions. Each child organization does not have its own limit of 500 files per 24 hours.

Cisco Umbrella SIG Advantage Threat Grid Quota

There is no limit to Threat Grid files for SIG Advantage licenses. To determine your current package, navigate to Admin > Licensing. For more information, see Determine Your Current Package. See also, Cisco Umbrella Packages.

Access to Threat Grid's dashboard, as integrated with Umbrella, has a number of features disabled which are only available to full Threat Grid Cloud customers. If you are a Threat Grid Cloud customer and have access to the full functionality of Threat Grid, you can link your Umbrella account to your Threat Grid Cloud portal. For more information, contact your account manager or Threat Grid support.

Monitor and Review Threat Grid Malware Analysis

Umbrella does not provide you with information about Threat Grid's activities. You must log into Threat Grid to view files that have been submitted to Threat Grid by Umbrella's File Analysis feature. For more information about how to use Threat Grid, see Threat Grid's Help which is available from the Threat Grid dashboard.

Files submitted by Umbrella to Threat Grid and that become marked as malicious can be reviewed under the File Retrospective section of Umbrella's Overview report. For information about how to get a better understanding and visibility into files marked as malicious by Threat Grid, see File Retrospective Events and Threat Grid.

Supported Files

The following file types are supported for submission to Threat Grid:
bat, bz2, chm, dll, doc, docx, eml, exe, gz, hta, hwp, hwt, hwpx, iso, jar, jtd, jtt, jtdc, jttc, lnk, msg, msi, mhtml, rar v5, rtf, xls, xlsx, ppt, pptx, pdf, ps1, sep, slk, swf, tar, vbe, vbn, vbs, wsf, xml, xps, xz, zip, 7-zip

The following mime types are not supported for submission to Threat Grid: text/html

MS Office documents, PDFs and executables are all submitted to Threat Grid.

For more information about supported file types, see Threat Grid documentation accessible through the Threat Grid dashboard under Sample File Types.

Threat Grid Sandbox

The first time you enable Threat Grid Malware Analysis, you must select a sandbox region: Europe or North America. Once selected, this location cannot be changed. This sandbox is a protected environment within which Threat Grid is able to detonate unknown files to determine whether or not they are harmful. Not all files submitted to Threat Grid are sandboxed.

Enable Threat Grid Malware Analysis

Like File Inspection, Threat Grid Malware Analysis can only be enabled through the Web policy's wizard.

  1. Navigate to Policies > Management > Web Policy expand an existing ruleset or click Add to add a new ruleset.
  2. Under Ruleset Settings, for File Analysis, click Edit.
  1. If disabled, enable File Inspection.
    Note: File Inspection is disabled by default.
  1. Enable Threat Grid Malware Analysis.
    Note: To enable Threat Grid Malware Analysis, File Inspection must be enabled.

a. If you are enabling Threat Grid Malware for the first time, select a Sandbox Region (North America or Europe), acknowledge that you understand that this location cannot be changed, and then click Save.
Note: The region you select should match the region for which your Threat Grid API key was generated. Europe uses panacea.threatgrid.eu and North America uses panacea.threatgrid.com.

Your new sandbox region is set and cannot be changed.
b. From the email you receive from Threat Grid, use your credentials to change your password, accept Threat Grid's End User Agreement and log into Threat Grid.
Note: You must log into Threat Grid within 36 hours of setting your sandbox region.


Enable File Inspection for the Web Policy < Enable Threat Grid Malware Analysis > Test File Inspection

Updated 4 months ago

Enable Threat Grid Malware Analysis


Web policy only

Suggested Edits are limited on API Reference Pages

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