Quickstart: Security Activity Using Cloud Security API

When you complete this Quickstart, you will be able to:

• Understand the new Umbrella API.
• Create an Umbrella API key and access token.
• Make your first API call and retrieve Security activity information.

In this Quickstart, we use the terminal, Umbrella API, and the JSON visualizer. This tool lets you easily retrieve information from the Umbrella API.

About Umbrella

Cisco Umbrella offers flexible, cloud-delivered security. It combines multiple security functions into one solution, enabling you to extend data protection to devices, remote users, and distributed locations anywhere. Umbrella is the easiest way to effectively protect your users everywhere in minutes.

Reserve the Sandbox (optional)

Reserve Cisco Umbrella Secure Internet Gateway Sandbox.

After you sign in or sign Up, click Reserve in the upper right corner. In the dialog window that appears, choose an available time slot and click Reserve.

Sandbox provisioning takes up to 7 minutes. When the Sandbox is ready, you receive the following email with Umbrella Dashboard credentials.

Navigate to https://login.umbrella.com/sso.

Paste Username and Umbrella Password in the related fields.

Generate an API Key in the Umbrella Dashboard

After you log in to the Umbrella dashboard, select Admin > API Keys and click on the + symbol in the top-right corner.

Select the Reports option and click Create.

Store these API keys and Org ID in a safe location.

Note: Treat API keys as passwords. Do not store or share them in an unsafe manner.

Requesting Historical Umbrella Security Activity Information

This summary contains high-level statistics that you can use for many tasks, such as creating a weekly automated report.

Example of the command that generates OAuth token

curl --user '6980d13c**********d01e73d****28:8a***********599d49e51ce********6' --request POST --url 'https://api.umbrella.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \                                                   
-d 'grant_type=client_credentials'

Paste the API Key and Key Secret that you generated in Umbrella Dashboard in the following command.

Note: Use with Sandbox credentials only.

curl --user 'PASTE_API_KEY:PASTE_KEY_SECRET' --request POST --url 'https://api.umbrella.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

When you execute the command in the terminal window, the output should be similar to the following example:

{"token_type":"bearer","access_token":"cmVwb3J0cy51dGlsaXRpZXM6cmVhZCBsImtpZCI6IjcyNmI5MGUzLWQ1MjYtNGMzZS1iN2QzLTllYjA5NWU2ZWRlOSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1bWJyZWxsYS1hdXRoei9hdXRoc3ZjIiwic...OiJhZG1pbi5wYXNzd29yZHJlc2V0OndyaXRlIGFkbWluLnJvbGVzOnJlYWQgYWRtaW4udXNlcnM6d3JpdGUgYWRtaW4udXNlcnM6cmVhZCByZXBvcnRzLmdyYW51bGFyZXZlbnRzOnJlYWQgyZXBvcnRzLmFnZ3Jl...MzlL","expires_in":3600}

Note: An Umbrella OAuth 2.0 access token expires in one hour (3600 seconds). We recommend that you do not refresh an access token until the token is nearly expired.

Umbrella Reporting API provides visibility into your core network and security activities and Umbrella logs. You can read more here.

Copy the Umbrella OAuth 2.0 access token from the output and paste it into the following command.

 curl --location --location-trusted \
 --request GET --url 'https://api.umbrella.com/reports/v2/activity?from=-3days&to=now&limit=10' \
 -H 'Authorization: Bearer PASTE_ACCESS_TOKEN' \
 -H 'Content-Type: application/json'

Refer to the following example to see what the command should look like:

curl --location --location-trusted \
 --request GET --url 'https://api.umbrella.com/reports/v2/activity?from=-3days&to=now&limit=10' \
 -H 'Authorization: Bearer PASTE_ACCESS_TOKEN' \
 -H 'Content-Type: application/json'

The following command can write output in the report.json file.

 curl --location --location-trusted \
 --request GET --url 'https://api.umbrella.com/reports/v2/activity?from=-3days&to=now&limit=10' \
 -H 'Authorization: Bearer PASTE_ACCESS_TOKEN' \
 -H 'Content-Type: application/json' > report.json

Visualize Your Reporting Data

To visualize the Reporting Data (JSON), you can copy and paste the JSON at https://jsoncrack.com/editor.

This site generates a visualization that supports zoom-in and zoom-out.

Congratulations!

You have completed the Quick Start Lab. We hope it was quick and easy.

You can continue learning with the following Labs.