NS1 Enterprise DDI + Cisco Umbrella Quick Start Guide

Cisco Umbrella is a cloud security platform that acts as a first line of defense against threats on the internet and provides visibility into internet activity across all devices over all ports—even when users are outside of your corporate network. It uses DNS and IP layer enforcement to stop threats before they reach your endpoints. Instead of proxying all web traffic, Umbrella routes requests for deeper URL and file inspection without delays or negatively impacting the end-user experience.

NS1’s Enterprise DDI and Cisco Umbrella offer a unified solution that supports agile application deployment and delivery while protecting your most critical assets. Easy to use and simple to manage, the integration allows customers to get the best of intelligent DNS traffic steering behind the firewall while protecting outbound queries with Umbrella security.

Designed to be API-first, NS1 delivers flexible, next-generation DNS solutions that solve complex performance, traffic management, and automation challenges. With Cisco Umbrella’s predictive and analytical approach to security, DNS becomes a control plane for the modern enterprise.

Requirements:

• Must be running NS1 Enterprise DDI platform version 1.2 or higher.
• Must have an active Cisco Umbrella account. Learn more at http://umbrella.cisco.com.
• Must have a network device identifier created in your Umbrella account for each DNS container. Learn more about creating a network device at https://docs.umbrella.com/umbrella-api/docs/create-a-device.

Configuration

Before you begin:

• If this is your first time installing and configuring Enterprise DDI containers with NS1, please refer to the Docker Compose Installation & Setup Guide for detailed instructions.
• (One-time) Enhance device or console to call the Cisco Umbrella REST API to perform per-device or per-segment registration. One “deviceID” is needed for each device or segment that should appear uniquely in Umbrella.
• Copy the API key and secret from the Umbrella dashboard, and paste it into the device or management console in order to make calls against the API.

Note: The network device accepts DNS queries and determines if they are bound for the internet. If so, it adds EDNS information before forwarding to Umbrella’s resolvers.

Step one:  Obtain your organization ID and device IDs for each DNS container

1. Obtain your organizationID from the Umbrella dashboard, or by executing the following cURL command:

   curl -i -X GET --url "https://management.api.umbrella.com/v1/organizations/" --header 'Authorization: Basic %base64string%' 

   Note: Refer to the Cisco Umbrella documentation for details.

2. Obtain the deviceID for the DNS container by executing the following cURL command:

   curl -X POST -H "Content-Type: application/json" -d '{ "model":"ModelName", "macAddress":"0123456789ab", "name":"Name1", "serialNumber":"12345a", "tag":"your tag" }' "https://management.api.umbrella.com/v1/organizations/<organizationId>/networkdevices" --header 'Authorization: Basic %base64string%'

3. Repeat the previous step for each DNS container on which you want to enable the Umbrella integration.

Step two: Configure

Option A: Configure via web interface

1. Launch a web browser, and go to the HTTP configuration interface for the DNS container. By default, this is http://<dns-host-ip>:3301.
   Note: A security warning may appear due to the self-signed SSL/TLS certificates.

2. When prompted, enter the following username and password for basic authentication:
   username = ns1
   password = private
   Note: You can change the basic authentication credentials at any time under Configuration Manager > Actions.

3. Under Resolving Configuration, click the radio button next to Recursive Resolver.
   Note: Umbrella resolution will not function if this is not enabled.

4. Check the box next to Enable Cisco Umbrella.
   Notes:
   • If you have alternative recursive resolver forwarding set up, enabling Umbrella will void these configurations.
   • If you do not specify a device ID, Umbrella will still resolve queries, but they will not appear in your CISCO dashboard (unless you’ve created a “network identity” in Umbrella). Learn more at https://docs.umbrella.com/.
   • If you do not specify an organization ID, Umbrella will be unable to identify the internal IP address associated with each DNS query.

5. Click Commit to apply configuration changes.

6. Verify the configuration by making a DNS query (i.e. using dig utility) and logging into your Umbrella account to view this query and device in activity reports. In the Umbrella dashboard, go to Reporting > Core Reports > Activity Search.

7. Repeat steps 1-6 for each DNS container.

Option B: Configure via command line interface (CLI)

1. At the host’s command line, execute the following(where <organizationID> and <deviceID> are the values captured in step one):

   docker exec privatedns_dns_1 supd run --operation_mode recursive --enable_umbrella true --umbrella_org_id <organizationID> --umbrella_device_id <deviceID> 

2. Verify the configuration by making a DNS query (i.e. using dig utility) and logging into your Umbrella account to view this query and device in activity reports. In the Umbrella dashboard, navigate to Reporting > Core Reports > Activity Search. 3. Repeat steps 1-3 for each DNS container.

Option C: Configure via REST API

1. At the host’s command line, execute the following cURL command (where <organizationID> and <deviceID> are the values captured in step one):

   curl -X POST https://<dns-host-ip>:3301/commit -d '{ "operation_mode": "recursive", "enable_umbrella": true, "umbrella_org_id": <organizationID>, "umbrella_device_id": "<deviceID>" }' -k 

2. Wait approximately 30 seconds, and then confirm successful reconfiguration using the following command:
   

   curl -X POST https://<dns-hostname-ip>:3301/health -k 

   Note: Each verification test should return a value of zero.

3. Verify the integration is working by making a DNS query (i.e. using dig utility) and logging into your Umbrella account to see this query and device in activity reports. In the Umbrella dashboard, navigate to Reporting > Core Reports > Activity Search.

4. Repeat steps 1-4 for each DNS container.