Application Programming Interfaces for Cisco Umbrella
./intro
We take for granted nowadays that a WEB-service will have an API to be explored, somehow. Countless are the business cases for doing it — including being able to integrate with other services and fully customize services with a third-party platform.
Therefore developing an application with exposed APIs is seen as a requirement and there are a many advantages to doing so: Think of the ability to expand the product’s feature list without relying solely on a vendor’s development team; or even future-proofing the application — making it available for a multitude of platforms (WEB, mobile) and even; at the end of the day, the documentation methodology used in such product’s Architecture on the back-end sure makes use of this feature as well.
It’s no wonder such product Design characteristic becomes an important feature.
Cloud-native services have the upper hand when it comes to this, and naturally Cisco Umbrella as well. In this short article I wish to explore some of the APIs available for Cisco’s Umbrella and how you can get started with using them.
If you don’t know what Cisco Umbrella is, check this video.
./concepts
There are a few important Concepts you need to understand before I detail Umbrella APIs.
Skip to the “Umbrella API” section if you’re familiar with Restful API Architecture.
Let’s take a step back and cover the basics:
What is an API?
Application Programming Interface — put simply is the way a Web-Application communicates (send and receive) information to another Web-application.
What is REST?
Representational State Transfer is a Web-Application Architecture style.
Its origins date back to 1994/95, and is based on uniform and predefined Stateless operations, generally a JSON or XML format.
In this Architecture model, the server does not save states, meaning it responds to each operation and closes the connection with the client.
The client is supposed to save the state and perform any follow up requests needed for his demand.
Focus is on Fast performance, Reliability, Ability to Grow and Re-use of components.
REST-API then is the use of APIs with the REST architecture: stateless via HTTP calls.
There are only having 4 possible methods in RESTful APIs, each with its functions:
POST: Creates new resources/content
GET: Reads resources/content
PUT: Updates resources/content
DELETE: Deletes resources/content
Once a request is resolved, the server will return a Status Code:
2xx — if successful
4xx — if there was a Client error
5xx — if there was a server error
And if required, will also deliver a payload (in case of a GET method).
At the end of the day this is nothing more than the response from a function/method in a code.
By the way, a function or method is a section of code that will always perform the same actions and provide an expected kind of response.
A common security measure applied to API requests is the use of authentication with a given “Token” (which is nothing more than a combination of 2 strings: KEY and SECRET). Each KEY will have its own exclusive SECRET — make sure you keep a copy of both of them securely, preferrably in an offline data storage.
JSON: JavaScript Object Notation is a uniform data-interchange format, makes it easy for humans to read data.
Data is formatted this way: “KEY : DATA”
XML: eXtensible Markup Language is a formate to store and transport data, also designed to be easy to read
Its got a different purpose than HTML in the following sense:
HTML — Designed to display data
XML — Designed to carry data
Data is formatted this way <tag><value></tag>
A few other useful concepts:
Python: A fairly easy to use programming language with a good learning curve for automation and use with APIs.
Umbrella: Cisco’s “Secure Internet Gateway”, Umbrella leverages its knowledge of internet Domains and their reputation to provide security to DNS resolution. It enforces security controls to DNS requests. You can create rules in it following a format similar to: If a user is trying to access a domain known for X then apply policy Y. You can even apply more conditions to a rule, enforcing DNS security according to user AD groups/profiles/location/SSID and more. Reporting becomes a powerful tool with all these rules in place and the platform delivers all the reporting needs an enterprise may need.
./umbrellaapi
DISCLAIMER: Most information below, including chart 1 was written and put together by me — I looked for multiple sources and the most documentation possible to assemble all of this. If I missed any important detail, please let me know and I’ll update the article.
With these concepts now in mind, it’s time to focus on how Umbrella is allowed to interact with other applications via its API.
Umbrella uses Restful API architecture and allow its customers to export Reports, Setup networks, Apply policies to devices (which Meraki devices use, by the way) and even integrate customer’s SIEM and Threat Intel Platform into Umbrella’s dashboard.
This vast feature-set is divided into multiple APIs and may or may not be included in your Umbrella dashboard depending on the licensing you have.
I’ve gathered all the options and created a chart for what is known to work with what licensing model. You’ll also find information about what is known to be the minimum package for each API and a brief Summary with Use Cases for each option. This chart considers public documentation available in the official Umbrella API document, Cisco Live Presentations and for somethings, my own tests.
P.s.: You can access Cisco live presentation’s by registering here: https://ciscolive.com, you’ll need to have a CCO account, its creation is also available in the previous link.
Chart 1: Umbrella APIs and their use cases
./testing
So now you know what Umbrella APIs are all about, what happens next for an engineer — after reading/researching something — is to get his hands dirty (metaphorically speaking), let’s do it.
When it comes to this subject, there are many ways to do it, I’ll list some good options below:
1: Devnet Sandbox
Cisco has a great Free platform for its developers (who have an account in DevNet) called DevNet Sandbox.
If you know dCloud, it follows the same principle, you login and schedule a time-slot to get a segmented virtual instance of a particular product/technology to use.
In this case, “sandbox” is a virtual environment for development purposes.
You can Register and learn more here: https://developer.cisco.com/site/sandbox/
2: Real Services
If you’re using Umbrella services already, then you can also access the API documentation (links thoughout this paper) and try on your organization’s dashboard.
Now i’m going to walk you through the steps to get started with the Umbrella API in this scenario.
Step 1: Know your API
First off, determine what API services you’re willing to test and ensure you have access to the minimum package listed in the chart 1.
In my example I’ll explore the “Management API”.
Access the documentation in this link: https://docs.umbrella.com/ and click on the desired API, you’ll be taken to the a page describing how to use the services of this API.
Image 1 — Accessing Umbrella API documentation
Let’s explore the use of the “Management API”, click on it to learn what functions you have and what sort of data you can expect to be returned from this method.
Image 2 — Exploring Umbrella API’s functions and responses
Step 2: Enable the use of the desired API in the Umbrella’s dashboard
All steps required to do this are really well documented in this section of the docs.umbrella.com page so I will not detail them in this article.
Make sure you take note of the authentication KEY:SECRET combination for your API. This will be required to make authenticated (thus validated) requests.
Step 3: Take note of your Umbrella dashboards’ Organization ID
Every customer will have an Organization ID (OrgID) attached to their dashboard (and security policies). This can be easily found once you login to the dashboard which you generated the APIs, at the URL you’ll find a 7 digit number which is the ORG ID.
Image 3: Locating the Organization ID of an Umbrella Dashboard
Step 4: Try the functions with your API token
Finally, with the API tokens and OrgID in hands, you can finally start testing the API and what you can expect from it.
Head to the “Management API” reference document and as an example I’ll extract the names of the networks I have configured in my dashboard (it’s a GET function).
In the example below you’ll see me add:
1. Org ID; 2. API KEY (in the “username” field) and; 3. API SECRET (in the “password” field).
The outcome is the retrieval of networks configured in our dashboard, with information like “Network Name”, “time created”, “status (active/inactive)”, “IP address” and other useful info:
Image 4: Finally trying the API
./conclusion
After this quick “getting started” article to Umbrella APIs you’ll be able to work on your customer’s (or company’s) requirements for developing powerful integration with the platform.
Hope you found this quick walkthrough useful, send a message in case you have any questions or anything to add here. Cheers!
./sources
Cisco live session programmability: BRKRST-2935
Cisco live session Umbrella: BRKSEC-1980
Cisco live / CCO registration: http://ciscolive.com
Umbrella API documentation: https://docs.umbrella.com/
List of Umbrella APIs: https://docs.umbrella.com/umbrella-api/docs/list-of-apis