Set Up Custom Integrations

Create a custom integration URL and use it to integrate Umbrella into other elements of your security infrastructure. Once integrated, you can send domain security threat information to Umbrella through the Umbrella Enforcement API.

Note: Umbrella supports up to 10 integrations per organization.

Prerequisites

• Full Admin access to the Umbrella dashboard.
• An Umbrella package that supports the Umbrella Enforcement API feature. For more information, see 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 Custom Integration URL
• Enable Third-Party Platform Integration
• Verify Custom Integration
• Logging and Reports

Create a Custom Integration URL

This integration URL includes the API key required to complete an integration.

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

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

3. Expand the custom integration to display its details.

4. Enable the integration, copy the integration URL, and then click Save.
   Note: The integration URL includes the Umbrella Enforcement API endpoint and the
   customer key.

5. Use the copied integration URL to integrate your third-party platform with Umbrella. See Enable Third-Party Platform Integration.

Enable Third-Party Platform Integration

With your copied integration URL and its 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 domains are listed as a result of threat events.

View Threat Events In Umbrella

1. Navigate to Policies > Policy Components > Integrations and expand your custom integration.
   Note: The integration must be enabled and active.

2. Expand Domains and view a searchable list of domains returned by the third-party integration.

View Threat Events Through the Umbrella Enforcement API

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

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, add the name of your integration in Filter by Identities & Settings and then click Run Filter.

3. Expand the entry, to view events added to your custom integration.

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