Understand the Umbrella Enforcement API for Custom Integrations

Introduction

This document describes the Umbrella Enforcement API for custom integrations.

What is the Umbrella Enforcement API?

The Umbrella Enforcement API allows partners and customers with their own homegrown SIEM/Threat Intelligence Platform (TIP) environments to inject events and/or threat intelligence into their Umbrella environment. These events are then instantly converted into visibility and enforcement that can extend beyond the perimeter and thus the reach of the systems that might have generated those events or threat intelligence.

The Enforcement API can ingest events in the generic event format described in this API documentation and can support ADD, DELETE, or LIST functions.

Note: If you do not have the Umbrella Enforcement API for custom integrations in your Umbrella dashboard and would like to have access, please contact your Cisco Umbrella representative.

Why would I use it? 

You might already process, manage, and curate your own threat intelligence system and processes that result in the desire to take actions on domains identified as malicious or suspicious. In that case, once a decision has been made that an event needs to be actioned on (for example, converted into protection), rather than manually adding protection to Umbrella for enforcement purposes, you can use the Enforcement API to automate this process and instantly enforce protection based on domains associated with the event.

This allows your security team to focus their time and effort on investigation rather than the ongoing configuration of Umbrella. It allows your security team to stay within their tools and processes instead of having to jump into the Umbrella dashboard to update destination lists. In essence, you are able to create a destination list in Umbrella from an external source that you manage directly through the API, then choose to block those destinations for identities within Umbrella.

How Would I Use It? 

ADD an Event to the Enforcement API

Once an event has been added, the Enforcement attempts to extract domains from the event.

Note: Support for IP addresses and URLs are added in the future.

• An event can contain any amount of the original event details you’d like, but does have to adhere to the specifications described in the API documentation.

  

  Note: Support for surfacing event details within the Umbrella dashboard may be added in the future.

• If a domain is extracted, it is validated by the Cisco Umbrella security graph to ensure it’s not a known good domain that is likely to result in false positives or already otherwise deemed malicious by the Cisco Umbrella security graph. 

• If it passes validation (for example, it’s unknown and safe to block), it’s added to a destination list associated with that custom integration and surfaced within the Umbrella dashboard as a custom security category.

• The custom security category can be blocked or allowed on a per-policy basis, to allow both active enforcement or passive “auditing” of suspicious requests.

LIST domains for an Enforcement API List

• If your workflow includes the unblocking of domains that were blocked because of previously injected events, a LIST request provides all of the domains currently included in the destination list associated with that integration.

DELETE Domain from Enforcement API List

• If your workflow includes the unblocking of domains that were blocked because of previously injected events, a DELETE request allows you to remove a domain from the destination list associated with that integration.

• If an incoming DNS request from one of your Umbrella identities is destined for a domain in the custom integration destination list, it is blocked or allowed depending on the custom integration's security setting associated with the policy that triggered it.

• The results are logged along with all other Umbrella events, accessible via the Activity Search, or via Amazon S3 using the S3 integration. Thus, traffic associated with the custom integration can optionally be ingested back into your SIEM/TIP and the feedback loop closed.

Walkthrough of Using the Enforcement API

Step 1: Create your custom integration

You can have up to 10 custom integrations at a time.

Note: If the organization is a child org of an Umbrella MSP, MSSP, or MOC, custom integrations shared from the console level shows up before integrations created at the child org level.

1. In Umbrella, navigate to Policies > Policy Components > Integrations and click Add.
2. Add a name for the custom integration and click Create.
3. Expand your new custom integration, check Enable, copy the integration URL and then click Save.
   
   

Step 2: Create your custom script(s).

1. See the generate_event and delete_domain sample scripts in the appendix of this document or use the API documentation to create your own scripts to generate the correctly formatted requests for either generating events, or deleting or listing domains. You’ll want to use the custom integration URL in these scripts going forward.

Step 3: Inject a sample event

1. Use the script you have created to inject an event into your custom integration. In our example, we’ve injected an event containing the domain “creditcards.com.”

Step 4: Check the destination list in the Umbrella dashboard

1. Return to Settings > Integrations and in the table expand your custom integration.
2. Click See Domains. A searchable list of the added domains appears and your sample event from Step 4 is now be in the list.
   
   

Step 5: Check the Admin Audit Log.

1. Another way to verify activity associated with your custom integration is by reviewing the Admin Audit Log.
2. Navigate to Reporting > Admin Audit Log.
3. Under Filters, enter the name of your custom integration in Filter by Identities & Settings, then click Run Filter.
   
   

When you expand the entry, you now see the event which resulted in your sample event (creditcards.com) being added to your custom integration.

Optional Step: List or Delete Domains

You may also wish to test to ensure you are able to list domains in your custom integration and delete domains in case you no longer wish to enforce against the domain or have it in your integration. Use the steps outlined in the API documentation to list and delete domains.

Configure Security Settings

Now that you’ve validated that you can inject events (and optionally list and delete domains), you can configure what you want to happen to DNS requests from your identities that are destined for domains in your custom integration’s security category.

1. Navigate to Policies > Security Settings and under Integrations, check your enabled integration (in this example, FireEye)and click Save.
   
   115014145103
   

View Reporting for Your Custom Integration

Generate DNS requests from one of your identities (for example, Networks or Roaming Computers) destined for the domain in your custom integration (“creditcards.com” in our example). From the client’s perspective, you now see the appropriate block or allow result depending on how you configured your security settings.

1. Navigate to Reporting > Activity Search and under Security Categories select your custom integration (in this example FireEye) to filter the report to only show the security category for FireEye.
   
   115013981706
2. Click Apply to see the activity for the time period selected in the report.
   
   

You can also view the Activity Volume report to see the snapshot or trend over time tally reports including your custom integration(s).

1. Navigate to Reporting > Security Activity Volume.
2. Under Event Type, select Integration.
   
   115013982286
   
   

Configure your S3 integration for log storage and consumption (Optional)

If you’d then like to feed your Umbrella logs containing all of the requests for your environment back into your SIEM/TIP environment, you can do so using our S3 integration, which allows you to stream your DNS activity events back.

Appendix: Example Scripts

These perl scripts provide guidance on how you can generate an event for your custom integration. Please substitute the customerKey value from your Integration in both scripts. Note, these scripts are provided as examples and customization or updates may be required.

generate_event.pl:

#!/usr/bin/perl -w

# Custom integration - ADD EVENT URL

my $cust_key = 'https://s-platform.api.opendns.com/1.0/events?customerKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';

die "Usage: $0 - Please supply a domain\n" if @ARGV < 1;
my $domain = $ARGV[0];

my $json_blob = "{
    \"alertTime\" : \"2013-02-08T11:14:26.0Z\",
    \"deviceId\" : \"ba6a59f4-e692-4724-ba36-c28132c761de\",
    \"deviceVersion\" : \"13.7a\",
    \"dstDomain\" : \"$domain\",
    \"dstUrl\" : \"http://$domain/a-bad-url\",
    \"eventTime\" : \"2013-02-08T09:30:26.0Z\",
    \"protocolVersion\" : \"1.0a\",
    \"providerName\" : \"Security Platform\"
}";

my $curl_request = "curl '" . $cust_key . "' -v -X POST -H 'Content-Type: application/json' -d '" . $json_blob . "'";

my $results = exec($curl_request);

delete_domain.pl:

#!/usr/bin/perl -w

# Custom integration - DELETE URL

my $cust_key = 'https://s-platform.api.opendns.com/1.0/domains?customerKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';

die "Usage: $0 - Please supply a domain\n" if @ARGV < 1;
my $domain = $ARGV[0];

my $curl_request = "curl '" . $cust_key . "&where[name]=" . $domain . "' -v -i -g -X DELETE -H 'Content-Type: application/json'";
my $results = exec($curl_request);