Set Up Custom Integrations

To get started, log into Umbrella and follow the steps in this guide to configure your third-party security platform integration. We recommend that you review the documentation for your security platform or appliance before you start the integration.

Note: Umbrella supports up to 10 integrations per organization.

Prerequisites

To enable a custom integration, check that you have met the following requirements:

• Full Admin user privileges on the Umbrella dashboard.
• An Umbrella package that supports the Umbrella Enforcement API feature. For more information, see Cisco Umbrella Packages.

Additional Prerequisites for Cisco AMP Threat Grid

Umbrella integrates with Cisco AMP Threat Grid through the AMP Threat Grid API.

• Cisco AMP Threat Grid dashboard access
• Cisco AMP Threat Grid account API key

Note: Cisco AMP Threat Grid appliances and endpoint are not supported.

Table of Contents

• Create Customer Key
• Enable Third Party Platform Integration
• Verify Custom Integration
• Add Custom Security Setting to a Policy
• Logging and Reports

Create Customer Key

1. In Umbrella, navigate to Policies > Policy Components > Integrations and click Add.

2. Add a name for the custom integration and click Create.

3. Click the custom integration to display its details.
4. Check Enable, copy the integration URL, and then click Save.
   Note: The integration URL includes the Umbrella Enforcement API endpoint and the
   customer key.

Enable Third-Party Platform Integration

With your customer key, you can configure a third-party security event or threat intelligence platform to send domain information to the Umbrella Enforcement API.

Note: Each security information and event platform or appliance may require a unique set of configuration steps to enable the integration with Umbrella. We recommend that you review the documentation for your third-party platform.

To send security information events to Umbrella, the integrated third-party platform must generate the required domain information for the event and create an HTTP POST request to the Umbrella Enforcement API. For more information about the required event and domain information fields, see Umbrella Enforcement API.

Verify Custom Integration

Once you enable an integration, you can use the dashboard or Umbrella Enforcement API to verify that events reach Umbrella from the third-party platform or security appliance.

View Custom Destination List

In the dashboard, follow these steps to view the Security Settings page that contains the custom destination list for the integration.

1. Navigate to Policies > Policy Components > Integrations and expand your custom integration.

2. Click See Domains to view a searchable destination list.
3. View the list of blocked domains in the destination list.

View Admin Audit Log

The Admin Audit Log Report contains the information about your administrative activities associated with your custom integration. For more information, see Admin Audit Log Report.

View the contents of the Admin Audit Log Report:

1. Navigate to Reporting > Management > Admin Audit Log.
2. In the Filters area, enter the name of your custom integration in Filter by Identities & Settings, and then click Run Filter.

When you expand the entry, you can see the events added to your custom integration.

List the Blocked Domains

The Umbrella Enforcement API provides an endpoint to list the destinations in the custom destination list. For more information, see Umbrella Enforcement API Request Samples.

Add Custom Security Setting to a Policy

To start to block DNS requests for domains found in your custom destination list, add the security setting for the integration to a policy. For information about security settings, see Manage Security Settings.

1. Navigate to Policies > Policy Components > Security Settings and expand the list of security settings.
2. Scroll to Integrations and select a security setting for the custom integration.
3. Click Save.

Logging and Reports

If you enabled logging for the custom integration, you can view the events in the Activity Search or Activity Volume reports, or access your logs in a Cisco-managed or self-managed Amazon S3 bucket.

View Reports

Generate DNS requests from one of your identities—for example, Networks or Roaming Computers—destined for a domain in your custom integration. In the report, you can view the traffic from the request and identify if Umbrella blocked or allowed the request depending on how you configured your custom security settings.

1. Navigate to Reporting > Activity Search.
2. Locate Filter > Filter by Security Categories. Select your custom integration to view the network traffic and requests for your identities.

The Activity Volume report also includes the destination requests and traffic for the custom integration.

1. Navigate to Reporting > Activity Volume.
2. Select View Trend Over Time.
3. In the table, expand Security > Integrations.

Access Logs in S3

Umbrella provides access to your logs through Cisco-managed or self-managed Amazon S3 buckets. You can stream your DNS activity events for your custom integration back into your threat intelligence or security event and information environment. For more information about Umbrella logs, see Manage Your Logs.

---

Third-Party Security Integrations < Set Up Custom Integrations > Custom Integration Best Practices