Guides
ProductDeveloperPartnerPersonal
Guides
ProductDeveloperPartnerPersonal

Custom Integration Best Practices

Umbrella supports the integration of third-party security events and domain information through the Umbrella Enforcement API and custom destination lists. We recommend several best practices to enable you to create the most effective destination lists for a custom integration.

Table of Contents

Known Domains and Destination Lists

As your platform sends events, Umbrella validates the domain information and adds suspicious or malicious domains to your custom destination block list. If your security platform registers a security event for a known domain, Umbrella may block that domain if the event information indicates that the domain is unsafe or unknown. As a result, your networks may not have access to certain websites or files.

Before you send events to Umbrella from a third-party platform, we recommend that you create a separate destination list to allow any known or safe domains. If the custom integration sets up a destination block list for a subset of your managed Umbrella identities, you can also create a specific destination allow list for those identities or policies.

Examples of Domains or Websites to Allow:

  • Home page for your organization.
  • Domains that represent services you provide that may have both internal and external records.
  • Cloud applications that Umbrella may not be aware of or include when evaluating a domain.

Benefits of Custom Destination Allow List

  • The custom destination allow list prevents blocks of known or safe domains. When Umbrella receives a new event, Umbrella first checks for the presence of the domain in the custom destination allow list. If the destination is present, the request is not blocked.
    Note: A destination allow list takes precedence over a destination block list when a domain is present in both lists.
  • The custom destination allow list isolates domains that may require further analysis. You can use the custom destination allow list for auditing the traffic in your networks or to generate reports.

Note: By default, the Global Allow destination list applies to all policies. If you add a domain to the Global Allow destination list, Umbrella allows the domain for all policies.

Add a Destination List

In the dashboard, create a destination list.

  1. Navigate to Policies > Policy Components > Destination Lists and click Add.
  2. Enter a name for the destination list.
  3. Select Blocked or Allowed, and add destinations.
  4. Click Save.

After you save the destination list, you can add it to an Umbrella DNS policy.
For more information, see Manage Policies.

Delete a Domain from Custom Destination Block List

You can remove a destination from the custom destination block list through the dashboard or the Umbrella Enforcement API. When you remove a destination from the custom destination list, your security appliance or platform may send a new event which includes the same domain. If this occurs, Umbrella may block the domain. To prevent unexpected blocks, we recommend that you create a destination allow list and add the domain to this destination list.

Remove a destination from a custom destination block list in the dashboard.

  1. Navigate to Policies > Policy Components > Integrations, then expand your custom integration.
  2. Click See Domains and find the domain name you want to delete.
  3. Click the x (Delete) icon.
  4. Click Close.
  5. Click Save.

Use the Umbrella Enforcement API to delete a destination from a custom destination block list.
For more information, see Umbrella Enforcement API Request Samples.

Set Up Custom Integrations < Custom Integration Best Practices > Manage Content Categories

Updated 11 months ago