The OpenDNS Umbrella Enforcement API Developer Hub

Welcome to the OpenDNS Umbrella Enforcement API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Umbrella Enforcement API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Introduction

 

Welcome to the Umbrella Enforcement API. The API is designed to give technology partners the ability to send security events from their platform/service/appliance within a mutual customer’s environment to the Cisco security cloud for enforcement. You may also list the domains and delete individual domains from the list. All received events will be segmented by the mutual customer and used for future enforcement.

In order to successfully integrate you will need to format your events to meet the public format included in this document. This API is a REST API and follows RESTful principles in implementation.

All responses are served as JSON and authentication is required for all requests. The API makes extensive use of query strings to retrieve and filter resources.

Note: The Enforcement API is only available for customers with the Platform Umbrella package, or partnering software companies that have entered into a business agreement with Cisco. For more information on packages, please see:* https://umbrella.cisco.com/products/packages


Authentication and Versioning

 

The API will be restricted to HTTPS and is hosted and available to make requests at: https://s-platform.api.opendns.com

Versioning in the API is handled via the url. All API endpoint urls will include a version including the major and minor version, following the pattern of Twitter's API.
Example: https://s-platform.api.opendns.com/1.0/events

Cisco reserves the right to add fields to the API endpoints and methods listed below. However, we will not remove any of the endpoints listed below in future versions of the API.

Customer authentication to the API is currently handled by a fixed UUID-v4 Customer key to be provided via the Integrations interface in the Umbrella dashboard. These keys must be supplied with each request to the API.

Example: https://s-platform.api.opendns.com/1.0/events?&customerKey=1111-2222-3333-4444


Limits, Responses, and Errors

 

All responses will follow RESTful practices including the correct HTTP response codes for successful and error states as well as returning arrays of resources and single resource for collection and read operations, respectively.

The following limits are in place on the API:

  • HTTP requests, including single or multiple event requests, are limited to a maximum total request size of 20 MB. This includes the request body, HTTP headers, and URI.
  • The API can handle both a single domain event being added or multiple events being added.
  • The maximum length of a domain is 255 characters as established by our data schema and RFC1034
  • Exceeding any of these limits will result in an HTTP 400 Bad Request being returned to the client.
  • The /domains endpoint is limited to 100 API calls per minute, per customer. HTTP 429 is returned if this limit is exceeded.

The API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with Cisco's servers.

HTTP Responses:

  • 202 Accepted—Everything worked as expected.
  • 400 Bad Request—Likely missing a required parameter or malformed JSON. Please check the syntax on your query.
  • 403 Unauthorized—Request had Authorization header but token was missing or invalid. Please ensure your API token is valid.
  • 404 Not Found—The requested item doesn't exist, check the syntax of your query or ensure the IP and/or domain are valid. If deleting a domain, ensure the id is correct.
  • 500, 502, 503, 504 Server errors—Something went wrong on our end.

API Endpoints

 

This section outlines three endpoints:

POST /events to add a domain to a domain list
GET /domains to gather a list of domains already added
DELETE /domain to delete a domain from the list.


POST /Events

 

Posts a Malware event to the API for processing and optionally adding to a customer's domain lists.

The POSTed event must conform to our Generic Event Format, which is outlined below.

Note

Requests to this endpoint must be sent with the Content-Type: application/json header

Example request for a single event

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}'

Example request for multiple events

In order to post multiple events to the endpoint, simply add the events following the generic event format in a JSON array as shown below.

curl 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
-v -X POST \
-H 'Content-Type: application/json' \
-d '[{
    "alertTime": "2013-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "internetbadguys.com",
    "dstUrl": "http://internetbadguys.com/a-bad-url",
    "eventTime": "2013-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
},{
    "alertTime": "2015-02-08T11:14:26.0Z",
    "deviceId": "ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion": "13.7a",
    "dstDomain": "moarinternetbadguys.com",
    "dstUrl": "http://moarinternetbadguys.com/a-bad-url-again",
    "eventTime": "2015-02-08T09:30:26.0Z",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
}]'

GET /Domains

 

To gather the lists of domains already added to the shared customer’s domain list, run a GET request against the domains endpoint of the API.

An initial query will list a page of the first 200 results from the list, which are not ordered in any specific way. The limit for any query for this endpoint is 200.

Example request to get the Domain List

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \ 
-v -X GET

Domain List Query Results

Results are displayed in two arrays: meta and data

The meta array shows which page of results is available, the number of results and next and previous available pages to query. If ‘prev’ is false, this is the first available page of results. If ‘next’ is false, this is the last available page of results. Otherwise, ‘next’ and ‘prev’ will provide a query formatted to show the next set of results.

The data array contains the domains in the domain list, along with a unique ID number for each domain.

{
meta: {
	page: 1,
	limit: 200,
	prev: false,
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=200"
	},
data: [
		{
			id: 2388,
			name: "maliciousdomain.com"
	},
	{
			id: 7527,
			name: "phishingsite.com"
	},
	{
			id: 57769,
			name: "nastymalware.ru"
	},
	{
			id: 60758,
			name: "hackingsiteforkids.co.uk"
	},
	]
}

Pagination for /LIST Domains

In order to paginate the additional domains in a list, simply append “page=#” and “limit=###” to the query. The meta results from the initial query will show an example of this. In this example, we will show page three where the limit is 50 queries per page:

curl 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=3&limit=50' \ 
-v -X GET

Example result for additional pagination

{
meta: {
	page: 3,
	limit: 50,
	prev: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=2&limit=50",
	next: "https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&page=4&limit=50"

	},
data: [
		{
			id: 9911797,
			name: "moremalware.com"
	},
	{
			id: 9911799,
			name: "russianhackers.com"
	},
	{
			id: 9939981,
			name: "mysteriousmalware.se"
	},
	]
}

DELETE /Domain

 

To delete a domain from the shared customer’s domain list, run a DELETE request against the domains endpoint of the API. The DELETE should include the numerical identifier (id) as specified in the LIST endpoint or the actual domain name you’d like to delete. Examples of both are provided below.

If successful, this endpoint will return HTTP 204 - No Content. Any other return besides 204 is unsuccessful.

IMPORTANT NOTE: The domain is contained in the URL for the Delete function and as such, must be URL-encoded or percent encoding. UTF-8 and Unicode encoding will not work and should be used.

Example query to delete by id:

curl -v \
     -i \
     -X DELETE \
     -H 'Content-Type: application/json' \
     'https://s-platform.api.opendns.com/1.0/domains/xxxxx?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

Example query to delete by domain name:

curl -v \
		 -H 'Content-Type: application/json' \
		 -X DELETE 'https://s-platform.api.opendns.com/1.0/domains/domaintodelete.com?customerKey=XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' -v -X DELETE

Generic Event Format

 

The following is an example of how to arrange the public event format.

POST https://s-platform.api.opendns.com/1.0/events/
REQUEST
{
    "deviceId":"ba6a59f4-e692-4724-ba36-c28132c761de",
    "deviceVersion":"13.7a",
    "eventTime":"2013-02-08T09:30:26.0Z",
    "alertTime":"2013-02-08T09:30:26.0Z",
    "dstDomain":"groogle.com",
    "dstUrl":"https://www.groogle.com/finance?q=NASDAQ:AAPL",
    "protocolVersion": "1.0a",
    "providerName": "Security Platform"
    From here down is optional
    "disableDstSafeguards":true
    "dstIp":"8.8.8.8",
    "eventSeverity":"Severe",
    "eventType":"Cryptolocker",
    "eventDescription":"Win32/Crilock.A",
    "eventHash":"d41d8cd98f00b204e9800998ecf8427e",
    "fileName":"%AppData%RoamingMicrosoftWindowsTemplatesrandom.exe"
    "fileHash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "externalUrl":http://groogle.com/malware.html,
    "src":192.168.100.101
  }
    

Generic Event Format Field Descriptions

 

Note

The fields in bold are mandatory and must be supplied. The non-bolded fields are optional but best practice is to pass in as much information as possible. It's important to note that although this information must be provided when using the API, not all of it is utilized in the destination lists within Umbrella.

Field
Description

"deviceID"

The ID of the device sending the event.

"deviceVersion"

Version of device sending the event.

"eventTime"

Time event was detected, must match the following style 2013-02-08T09:30:26Z

"alertTime"

Time event was sent to Umbrella must match the following style 2013-02-08T09:30:26Z

"dstDomain"

The destination domain, specified following RFC3986 encoding guidelines and without the protocol included. An example would be 'www.internetbadguys.com'

"dstURL"

The destination URL encoded using standard percent-encoding following RFC3986](http://www.ietf.org/rfc/rfc3986.txt) encoding guidelines. An example would be 'http://internetbadguys.com/security?foo=there%20are%20spaces%20here'

"protocolVersion"

The version of the protocol for the API. Value should always be "1.0a"

"providerName"

The provider name for the API. Value should always be "Security Platform".

"disableDstSafeguards"

Boolean value, either 'true' or 'false'. 'false' is the same as not providing this field at all. A value of 'true' will will bypass validations normally performed against submitted events before adding them to any of the domain lists in Umbrella. This safety checking is known as the Domain Acceptance Process and is present to protect against third party automated systems accidentally submitting events with highly popular or known safe sites like google.com and potentially causing interruptions in service for your users.
The Domain Acceptance Process is described in detail in this section of the documentation: https://docs.umbrella.com/developer/enforcement-api/domain-acceptance-process2/
When disableSafeguards is set to true, the following parts of the acceptance process are skipped:
Ensuring that the domain is not in an list of known good domains (which is generally a list of the internet's most popular domains)
A check against the Cisco Umbrella Investigate API to see if domain is either not safe, unknown, or known good.
Normally, if a domain is known good on either of the checks listed above, the Security Platform will not submit the domain or URL and will not be present in your domain list or possibly blocked. Setting this value to true will increase the likelihood of a false positive or an outage in service tied to popular domains being blocked.

"dstIP"

The destination IP of the domain, specified in IPv4 dotted-decimal notation. An example would be '8.8.8.8'

"eventSeverity"

The parter threat level or rating, eg: severe, bad, high, etc.

"eventType"

Common name or classification of threat.

"eventDescription"

Variant or other descriptor of event type.

"eventHash"

A unique hash of the event.

"fileName"

Path to file exhibiting malicious behavior.

"fileHash"

SHA-1 of file reported by appliance.

"externalURL"

External page containing additional information about event.

"src"

IP/Host of the infected computer/device that was patient 0 for the event.


Domain Acceptance Process

 

When posting data to the Security Platform API, the following steps are taken before the domain appears in a customer's block list. The optional parameter "disableDstSafeguards" can be used to bypass parts of this process as outlined in the Generic Event Format Field Descriptions. The domain acceptance process is outlined from start to finish here:

  1. An external source identifies malicious activity occurring when a user visits a particular URL. This source could be a third party vendor’s data feed, an entry in one of your security logs or something identified as malicious on a security related website

  2. The event is sent to the Umbrella Security Platform API via a POST request, following the steps and syntax outlined earlier in this documentation.

  3. Before the domain included API POST event is added to the specified Umbrella customer’s block list, the following checks are performed:

    • Does the domain already exist in the Umbrella Security global block list under one of the Security Categories? Even if the domain does exist in the Umbrella global block list, it is still added to the customer’s block list.

    NOTE: In order to do the check against our global block list, the domain is submitted to the Cisco Umbrella Investigate API, which returns a score of -1 if the domain is malicious.

    • Is the domain considered benign, or safe, under the Cisco Umbrella Investigate? A domain is considered safe when a score of +1 is returned from the Investigate API. Domains that are considered safe are not added to the block list.

    The sorts of domains that are typically safe include ones that the Cisco security labs team has marked as safe or any domain found in the Alexa Top 1000.

    • Is the status of the domain uncategorized? A domain is considered uncategorized when the Umbrella Investigate API returns a score of 0. If a domain is uncategorized, it is added to the Umbrella customer’s block list.

    • Is the domain already present on the customer’s allow list within the organization? If so, the domain will still be added to the customer’s block list, however, please note that entries on a customer allow list will trump any customer-owned or Umbrella-owned block list.

  4. If the domain is then added to the customer’s domain list, then any domains in that list will be blocked in accordance with that customer’s Umbrella policy security settings.


});