02/09/2020 – FuZzy loGiC

Cisco Umbrella has number of RESTful Application Programming Interfaces (API) – broadly categorized based on their purpose.

Management API — Mainly for administration task like to manage networks (add / remove) or roaming clients etc.

Reporting API — To pull information on security activities, top destinations, top categories etc.

Enforcement API — Use to integrate with other security products to enforce the policy using Umbrella.

Investigate API — Helps to query Cisco Umbrella’s security data lake created by security research team.

Network Device API — For device registration and policy related applications.

Legacy Network Device API (deprecated) — Used to register legacy network devices to Umbrella to get visibility of DNS traffic flow. We can use Network device API to achieve the same results.

One of the main use-case is to allow customers to perform a variety of Umbrella-related functions without performing configuration steps in a dashboard. Another use-case is to integrate Umbrella with other security products to automate the work-flow such as remediation process. API can also use to pulling real-time threat information to the monitoring systems or collect logs from Umbrella Amazon S3 bucket to Security information and event management (SIEM) tools for further analysis.

Currently Umbrella use HTTP Basic Authentication with API Key and Secret Key. The Cisco documentation may refer the keys as Username and Password.

Step 1: Generate API key pair

For Management API, Reporting API, Network Device API and Legacy Network Device API use Umbrella dashboard -> Admin -> API Keys section to generate the key pairs.

For Investigation API you must go to Umbrella Investigation console (via Umbrella Dashboard) and click “Investigate API Access” link under the tabs

For Enforcement API use Umbrella dashboard -> Policies ->Integrations. Note: Unlike other API Key, Enforcement API key is not a pair of keys but a URL. Key is included in the URL

Step 2: Setup Postman

Download the Postman API Client APP from https://www.postman.com/product/api-client/

Step 3: Generate API request using Postman

From the Postman GUI -> Launchpad tab -> select “Create a request”

From the new GET tab -> select “Authorization” tab. Then on that table select “Basic Auth” option from the TYPE drop down options. After you select the Basic Auth please provide the Umbrella API keys on the right hand side option. For “Username” use Public Key and “Password” use Secret Key. Leave rest of the settings to default in Postman.

To generate an API request we need Umbrella Org ID (organization Identity). Every Umbrella instance in Umbrella cloud is identified using a Unique Org ID. Every customer Umbrella dashboard has unique Org ID in the URL. https://dashboard.umbrella.com/o/{organizationId}/#/overview