API & Integrations - Zscaler Threat Share Integration

This article contains information on the Zscaler Threat Share integration, which enables sharing of malicious domains from Mimecast to Zscaler, enhancing security, supporting multiple configurations, and providing quota monitoring for improved threat management.

Overview

The Zscaler Threat Share integration enables sharing of malicious domains from your Mimecast account to your Zscaler account.

Benefits

By sharing threats from Mimecast to Zscaler:

• An additional layer of security is provided in situations where a domain is being used across multiple attack vectors, especially in the case of a persistent threat actor.
• By sharing threats seen from one platform to another, you increase the overall strength of your security ecosystem.
• Multiple configurations allow different sources in Mimecast to have different actions in Zscaler, allowing you to customize the level of severity for each type of detection to fit your organization's needs.
• Multiple configurations also allow for a many-to-one tenant configuration, where you may have one Mimecast account and multiple Zscaler accounts.

Details

Sharing Threats

Mimecast's URL Protection performs various checks against URLs within an email in transit or when a user attempts to click a link within an email. We can source the domain where the scan result is malicious.

Additionally, Mimecast's Impersonation Protection identifies domains used in a phishing attack where the sender domain is similar to a domain within your Mimecast account, or similar to a list of domains uploaded to the custom domains list.

In each of these cases, the integration can add the domain to a URL category in Zscaler, which can be used with Zscaler URL & Cloud App Control policies.

Once configured, each integration configuration instance will create an associated URL category in Zscaler. This will be used as the destination of any malicious domains sourced from Mimecast by this specific integration configuration instance. Up to 10 individual configurations can be created, allowing different source and destination URL categories, each with their own policy application.

Once the integration is configured, a Zscaler administrator should apply the URL categories in to desired polices with actions in Zscaler's ZIA Admin Portal. The URL categories by themselves will not provide protection.

Quota Monitoring

Each time a domain is shared with Zscaler, the integration will perform a URL quota check and alert the configured notification recipients when they are at 90% and 100% quota. When the quota in Zscaler has been exhausted, the integration will go into permanent error state.

If the quota in Zscaler has been exhausted, then you will need to do one of the following:

• Clear out older entries in the respective URL category in Zscaler’s ZIA Admin Portal.
• Reach out to Zscaler to purchase additional buckets.

Prerequisites

To make use of the Zscaler Threat Share integration in Mimecast, you need:

• A Mimecast Cloud Gateway account with Targeted Threat Protection URL Protection and/or Impersonation Protection.
• Policies configured in Mimecast for URL Protection and/or Impersonation Protection. These can be generic for the account, and do not require policies specifically for the integration.
• A Zscaler account.
• OAuth 2.0 Application (Okta, Azure Entra ID).

Integration Setup

To integrate Mimecast with Zscaler, perform the following Steps:

1. Log into Zscaler's ZIA Admin Portal.
2. In Zscaler's ZIA Admin Portal:

• • Create a new API Role using the Add API Role steps with the following permissions:
    • Policy Access: Full
    • Inside Access Control (Web and Mobile)
      • Custom URL Category Management
      • Override Existing Categories
  • Register your client application on your OAuth 2.0 Provider:
    • Okta
    • Microsoft Entra ID
  • Configure the scope claim in the <Zscaler Cloud Name>::<Org ID>::<API Role> format in the OAuth 2.0 provider application and copy this value.
  • Add your OAuth 2.0 authorization server to the ZIA Admin Portal.

3. Retrieve your Zscaler base URL:

• • Ensure your admin role includes the "Authentication Configuration" functional scope to access the following page:
  • Navigate to Administration | Cloud Service API Security.
  • On the OAuth 2.0 Authorization Severs tab, copy the base URL that is displayed within the table.

4. Log into Mimecast's Cloud Gateway Administration Console.
5. Navigate to Integrations | Integrations Hub.
6. Find the "Zscaler Threat Share" integration tile and select the Configure option at the bottom of the tile.
7. Review and accept the terms and conditions pop-up.
8. Provide an application name to differentiate multiple instances of the threat share integration.

• • In addition to this field being used to identify a specific configuration on the Mimecast side, the name will be prepended with "Mimecast " and used to name a newly created URL category in Zscaler upon saving this integration.
  • This field cannot be changed once initially set.

9. Provide an application description to better explain the purpose behind this specific integration configuration.

• • In addition to this field being used to explain a specific configuration on the Mimecast side, the description will be used to populate the description field on a newly created URL category in Zscaler upon saving the integration.
  • This field can be modified in Mimecast in the future, but this change will not be synchronized over to Zscaler after the URL category has been initially created.

10. Under Activate, provide the following fields obtained from Zscaler's ZIA Admin Portal:

• • Zscaler Base URL
  • OAuth 2.0 Provider Token Endpoint
  • Client ID
  • Client Secret
  • Scope 

Note:

If you are using Entra ID as your OAuth provider, the Scope entered into the Mimecast Administration Console will be in the format "api://<application client ID of the web API app registration in Azure>/.default", as described in the final section of the configuration guide. When using Okta, the Scope field should match the <Zscaler Cloud Name>::<Org ID>::<API Role> format as described in step 2 above.

11. Under Activate, select the period of time you want to go back in Mimecast logs to search for domains to add to the URL category that will be created. By default, the integration will start by pulling domains from the past 7 days of events in Mimecast.
12. Under Send, from Mimecast, select the sources to obtain domains from Mimecast:

• • Malicious Domains - These are domains sourced from Mimecast Impersonation Protection, where the domain similarity match was triggered.
  • Malicious URLs - Full malicious URLs from Mimecast URL Protection, where the scan result was malicious. This is more accurate, as it provides the full URL. However, this can cause the quota on the Zscaler side to fill up more quickly.
  • Malicious Domains extracted from URLs - The domain only from Mimecast URL Protection, where the scan result was malicious. By default, Zscaler appends a wildcard to the end of the domain to capture any path. This can help to preserve the URL quota on the Zscaler side.

13. Under Notification Configuration, add email addresses to receive alerts should the integration encounter a permanent failure.

• A maximum of 5 addresses can be specified and may include addresses for distribution groups.

14. In Zscaler's ZIA Admin Portal, Create or modify any desired policies to apply to the URL Category created.
15. Wait approximately 30 seconds for the integration to create and populate the URL category in Zscaler.
16. In Zscaler's ZIA Admin Portal, Create or modify any desired policies to apply to the URL Category created.

Troubleshooting

Error State and Notifications

Permanent Errors

A permanent error occurs when the integration is unable to proceed in sharing threats until manual intervention is performed. In the event of a permanent error, you should see the status change in the Integration Hub and the recipients specified in the Notifications section of the setup will receive an alert.

While in a permanent error state, the integration will not attempt to share any threats until resolved.

Example reasons for a permanent error:

• Expired or rotated API keys in Zscaler.
• Quota exhaustion for URL categories in Zscaler.

To manually return an integration to normal state after resolving a permanent error, edit the specific integration, and click save.

If the resolution of an error state requires changes, make them at this time. Otherwise, you may select save without changes. The integration will attempt to resume and return to a normal state or go back into a permanent error state.

Temporary Errors

If the integration encounters a temporary error, such as unexpected responses when making API calls to Zscaler or a Mimecast service degradation, then no action is required, and the integration will continue to attempt sharing threats until it automatically returns to a normal state or goes into a permanent error state. Temporary errors will not generate alert emails.

Threats observed while in an error state

The integration uses timestamp bookmarking when sharing threats. If the integration goes into an error state, the timestamp bookmark will not advance. This allows for threats observed while in an error state to be shared when the integration returns to a normal state, so long as the integration is not in an error state for more than 30 days.

If the integration is in an error state for more than 30 days and returned to normal, the last 30 days will be shared when returned to a normal state. To avoid sharing of older threats, you can delete and create a new integration configuration.

Opening a Support Case

If you need to open a support case for assistance with an integration configuration in an error state, you must include the Application Name, any email notifications you received, and your Mimecast hosting region (also known as your grid).