Umbrella has per-build APIs for easy integration with few security vendors like Check Point, FireEye, ThreatConnect, ThreatQ, ZeroFox. Umbrella also has the flexibility to create custom integration with most of the other security platforms. More information on integration with above vendors are documented here.
Destination List provides the fundamental security policy to blocking or allowing an internet connection to a destination. Destination list contain a list of internet destinations created based on security policies of an origination. A destination entry in the list can be a Domain Name, IPv4 Address or an URL.
The entries in the destination list can come from Threat Intelligence Platforms (TIP), Firewalls Appliances, Security information and event management (SIEM) or even homegrown systems. If for any reason, if a customer cannot integrate with Umbrella then the destination list can manually update via Umbrella GUI. Umbrella has bulk update feature to upload a file into a destination list. File must be in .txt or .csv format, with one destination entry per line, with a maximum of 5000 destination entries per file.
If new to Cisco Umbrella API and like to know how to interact with Umbrella using API client, please read my previous blog. This blog is focused on to create/update/deletion of destination list and its entries.
In real-world use case, customers have requirements to frequently update the entries of a destination list. The list of entries may collected from multiple threat intelligent sources. For example, domain A will be in a block list today but tomorrow (for some reason) customer like to remove from the block list and add it to the allow list. Manually performing these tasks will be cumbersome for an admin. Automation play an important to role in this use case.
In this blog we are focusing on 4 points
1. Create a destination Allow List
2. Create a destination Block List
3. Add destination list entries to a destination List
4. Delete an entry from a destination list or a destination list itself
1 — Create a Destination Allow List
POST https://management.api.umbrella.com/v1/organizations/{OrgID}/destinationlists
Umbrella has Allow & Block destination list. To create an Allow list we must specific that using “access” (string) parameter in the API body along with other required parameters. “isGlobal” is a boolean — either true or false. true value will make the destination list a global list in that Org. ”name”(string), to add name to a destination list. Optionally, we can add the destination list entries while creating the destination list or later.
Note: There is a small difference in the syntax when we are adding entries while creating the new destination list, we must add it in the “destination” array. If we are directly adding a new entry into an existing destination list then we don’t need add “destination” in the API body, just create an array and list the entries, which is shown later in this blog.
Below is a screenshot of my postman client as an example to show you the API body and URL. We can see that the “access” parameter is declared as “allow” to make this destination list as an Allow List. “isGobal” is false because we are creating a new non-default destination list. Global List is a default list in an Umbrella Org which applies to all identities. Non global list helps to enforce the list of destinations on sub-set of identities.
The “destination” array contain both domains and IPv4 address. Also please note the Domains counter and the IPs counter reflected in Umbrella GUI.
2 — Create a Destination Block List
POST https://management.api.umbrella.com/v1/organizations/{OrgID}/destinationlists
The only difference when compare to create a destination allow list is the “access” parameter in the API body.
Note: IPv4 address as an entry can be included only in Allow List, and URL as an entry can be included only in Block List. Domains name entries can be in both list.
Below screenshot shows you an example of Block list created with exact same parameters of as Allow list. Only the difference is with the “access” parameter is declared as “block” to create a destination block list.
The “destination” array contain both domains and URL. Also please note the Domains counter and the URLs counter reflected in Umbrella GUI.
3 — Add destination list entries to existing Destination List
To add a new entry into an existing destination allow list, we must first need to have the List “id”. To collect the list id, Retrieve all the destination list under the Org and choose the id for which we need to add an entry.
Step A — Retrieve and collect the destination list “id”
GET https://management.api.umbrella.com/v1/organizations/{OrgID}/destinationlists
To retrieve (GET method) no parameter is required in the API body. Just execute the GET method to the URL. Below screenshot shows you an example of the URL and the output. Make sure to have the correct OrgID .
From the GET output, pick the destination list in which you like to add/remove entries and note the “id”.
Step B — Add destination entries to the list
To add destination entries into an exiting destinations list is by adding the domains and IPv4 address into an array. Please refer the below screenshot example, note the URL which has the Destination List ID “id”, collected from previous step A. API body parameter is in JSON array format with destination entries. Because it is an Allow List, URL destinations cannot add and if you tried to add you will get error.
Here is another screenshot to show you how to add entries to an exiting destination Block list. The destination list “id” in the URL has been change to match the block list.
Please note that while adding URLs into a destination Block list. If it is a well know domain and the URL is very wide then we may get error. Check below screenshot for example.
In the above example, I have used “box.com” instead of “mypersonal.com”. In the output section we can see the message in the error “high_volume_list_domain”. Even if we tried to add the URL via GUI we will get the error as shown in below screenshot.
Please check this support article to learn more about the destination list entries and error messages.
4 — Delete an entry from a destination list or a destination list itself
Using DELETE method we can remove an entry from an allow / block destination list or the whole destination list.
Step A — Retrieve and collect the destination list “id”
To remove an entry from a destination list, we use destination “id” or list of “id”s. if you do not know the “id” then with GET method retrieve all the entries in a destination list and select the “id”or “id”s which you would like to remove.
Below screenshot is an example of GET output of a destination list.
Step B — Delete the entry /entries or a destination list
The main parameter required to delete an entry or destination list is to have the correct entry “id”.
Below screenshot is an example to delete an entry “www.malware.com” from an existing destination list. The syntax is same for both Allow & Block list. Select the entry “id”, insert it into the API body in JSON array format and execute. We cannot use domain names, IPv4 address or URL in the array to delete an entry.
To delete a destination list, use destination list “id” in the URL no API body parameter is required
DELETE https://management.api.umbrella.com/v1/organizations/{OrgId}/destinationlists/{destinationListId}
Below screenshot is an example to delete a destination list. In the example we used the “id” of destination list “VCD block List” to delete the destination list. It is very simple and straight to delete the whole entries of a destination list.
