Integrate Cisco SecureX with Cisco Umbrella

Introduction

This document describes the process to configure and verify the Umbrella integration with SecureX with the 3 available APIs.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Cisco Umbrella
• Cisco Secure X
• Cisco Threat Response

Components Used

The information in this document is based on these software and hardware versions:

• Umbrella account with DNS Advantage License
• Secure X

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Background Information

In order to fully configure this integration with all of its functionalities, you need access to these 3 APIs

• Reporting API (included in all licenses)
• Enforcement API
• Investigate API

In order to configure the Umbrella integration, you must first gather some information from your Umbrella instances and then complete the Add New Umbrella Module form.

Configure

Create Module

1. Log in to your Secure X account. If you do not have an account yet, you can create one with Cisco Secure Sign-On.
2. Navigate to Integrations > Add New Module. In the Available Integrations page scroll down to the Umbrella option and click Add New Module.   

Use these steps to collect the necessary information from your Umbrella Account to submit in the Add New Umbrella Module form.

Investigate API

1. In Umbrella, navigate to Investigate > Investigate API Access, click Create New Token and enter a title for the token, and then click Create New Token again.
2. Copy the Access Token value into the API Token field on the Add New Umbrella Module form.

Enforcement API

1. In Umbrella, navigate to Policies > Policy Components > Integrations, click Add and enter a name, and click Create.
2. Click the newly created integration name link, check theEnablecheckbox, andSave.
3. Click the integration name to display the integration URL. Copy the integration URL into the Custom Umbrella Integration URL field on the Add New Umbrella Module form.

Note: In order to integrate the Umbrella Enforcement API, you must be an admin in an Umbrella standalone org or child org instead of an admin of an Umbrella console.

Reporting API

1. In Umbrella, navigate to Admin > API Keys and click Create.

2. Under What should this API do?, click the Umbrella Reporting radio button and then click Create.

3. Copy the next values into the Reporting fields on the Add New Umbrella Module form:

   • API Key (Your Key)

   • API Secret (Your Secret)

   • Organization ID - from browser URL, the set of numbers between/o/and/#/

   • Request Timeframe (days)- Enter the timeframe (in days) for enriching sightings from the most recent DNS requests

Save Module

1. Fill out the API information in your Umbrella Module, click Save.

Create SecureX Dashboard

1. Once you added your module, you can navigate to Secure X and create a New Dashboard.

2. Under the available Dashboards, select your Umbrella module and add the Categories you are interested in seeing.

3. Click Save, and see your information populated via the API. 

Verify

Use this section in order to confirm that your configuration works properly.

Investigate

The Investigate API, allows you to add a feed to a CTR investigation, to see the disposition of a domain and enrich the investigation with other modules.

1. In order to verify this integration, make a new investigation in Cisco Threat Response. A Disposition provided by Umbrella can be found with a search for a known domain, such as cisco.com.

2. If you click under the domain in the Relations Graph, you also can pivot from there to the Investigate Dashboard in Umbrella.

Enforcement

With the Enforcement API, you can block or unblock a domain directly from an investigation.

1. In order to verify that the API works, you can block a domain seen in an investigation and that adds the domain to the policy block list in Umbrella.

2. In order to verify that the URL has been added to the block list, navigate to Policies > Policy Components > Integrations. Select your SecureX integration, and click See Domains. A window displays the added domains from CTR.

 3. If the domains are not blocked, on your Umbrella dashboard navigate to Policies > Policy Components > Security Settings. Under Integrations make sure that you have applied your desired list.

Reporting

The Reporting API allows you to see the information of your Umbrella deployments within SecureX.

You can verify the integration with an investigation of a domain you know has been seen in your environment in CTR.

In the CTR Investigation, the list of computers that have accessed a particular domain is displayed under Sightings.

Video

You can find the configuration information contained in this article in this video.

Related Information

• Technical Support & Documentation - Cisco Systems