Skip to main content

CISCO Umbrella Integrations

Introduction 

Cisco Umbrella is a cloud security platform that provides an additional line of defense against malicious software and threats on the internet by using threat intelligence. That intelligence helps prevent adware, malware, botnets, phishing attacks, and other known bad Websites from being accessed. 

Assumptions 

The procedures described in Section 3 assumes that a Log Collector has already been setup.   

Prerequisites 

    • You must have Full Admin access to Umbrella to create and manage Umbrella API keys or Umbrella KeyAdmin API keys. 

Requirements 

This integration is for Cisco Umbrella. It includes the following datasets for receiving logs from an AWS S3 bucket using an SQS notification queue and Cisco Managed S3 bucket without SQS: 

  • log dataset: supports Cisco Umbrella logs. 

Logs 

Umbrella 

When using Cisco Managed S3 buckets that does not use SQS there is no load balancing possibilities for multiple agents, a single agent should be configured to poll the S3 bucket for new and updated files, and the number of workers can be configured to scale vertically. 

The log dataset collects Cisco Umbrella logs. 

Advantages of Integrating with the Umbrella API 

The Umbrella API features a number of improvements over the Umbrella v1 APIs and the Umbrella Reporting v2 API. 

  • Intuitive base URI 

  • API paths defined by top-level scopes 

  • Intent-based, granular API key scopes 

  • API key expiration 

  • Updated API key administration dashboard views 

  • Programmatic API key administration 

  • API authentication and authorization supported by OAuth 2.0 client credentials flow 

  • Portable, programmable API interface for client integrations 

Before you send a request to the Umbrella API, you must create new Umbrella API credentials and generate an API access token. For more information, see Umbrella API Authentication.

 https://developer.cisco.com/docs/cloud-security/authentication/#authentication

Authentication 

The Umbrella API provides a standard REST interface and supports the OAuth 2.0 client credentials flow. To get started, log in to Umbrella and create an Umbrella API key. Then, use your API credentials to generate an API access token. 

Note: API keys, passwords, secrets, and tokens allow access to your private customer data. You should never share your credentials with another user or organization. 

Log in to Umbrella 

  • You can find your username after Admin in the navigation tree. Confirm that your organization appears under your username. 

Create Umbrella API Key

Create an Umbrella API key ID and key secret.

Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.

  1. Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.

  2. Click API Keys and then click Add.

    • The number of expired API keys appears next to the red triangle.
    • The number of API keys that expire within 30 days appears next to the yellow triangle.

  3. Enter a name and description for the key. A name must contain fewer than 256 characters. The description is optional.

    Umbrella API key name and description

  4. Check the key scopes and expand a key scope to view the scope categories. Check each scope category in a key scope to enable access to the API endpoints.

    image.png

  5. Choose Read-Only or Read / Write for the selected scope and resource.

    Umbrella API key scope access

  6. For Expiry Date, choose the expiration date for the key, or choose Never expire.

    Umbrella API expiry date

  7. (Optional) For Network Restrictions, enter a comma-separated list of public IP addresses or CIDRs, then click ADD.

    Note: You can add up to ten networks to your API key. You can only use your API key to authenticate requests for clients on the selected networks.

    Umbrella API network restrictions

  8. Click Create Key.

  9. Copy and save your API Key and Key Secret.

  10. Click Accept And Close.

Refresh Umbrella API Key

Refresh an Umbrella API key ID and key secret.

Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.

  1. Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console, navigate to Console Settings > API Keys.

  2. Click API Keys, and then expand an API key.

  3. Click Refresh Key.

    Umbrella API dashboard

  4. Copy and save your API Key and Key Secret.

  5. Click Accept and Close.

Update Umbrella API Key

Update an Umbrella API key.

  1. Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console, navigate to Console Settings > API Keys.

  2. Click API Keys, and then expand an API key. You can modify the API Key Name, Description, selected scopes and permissions in Key Scope, and Expiry Date.

    Umbrella API scope and expiry date

  3. For Network Restrictions, update the list of IP addresses and CIDRs. Click on the X to remove a network address.

  4. Click Save.

Cisco Secure Endpoint Integration Procedures 

Please provide the following information to CyTech: 

Collect logs from the Cisco Umbrella 

  1. Queue URL - URL of the AWS SQS queue that messages will be received from. For Cisco Managed S3 buckets or S3 without SQS, use Bucket ARN. 

  1. Bucket ARN - Required for Cisco Managed S3. If the S3 bucket does not use SQS, this is the address for the S3 bucket, one example is arn:aws:s3:::cisco-managed-eu-central-1 For a list of Cisco Managed buckets, please see https://docs.umbrella.com/mssp-deployment/docs/enable-logging-to-a-cisco-managed-s3-bucket. 

  1. Bucket Region - Required for Cisco Managed S3. The region the bucket is located in. 

  1. Bucket List Prefix - Required for Cisco Managed S3. This sets the root folder of the S3 bucket that should be monitored, found in the S3 Web UI. Example value: 1235_654vcasd23431e5dd6f7fsad457sdf1fd5. 

  1. Number of Workers - Required for Cisco Managed S3. Number of workers that will process the S3 objects listed. Minimum is 1. 

  1. Bucket List Interval - Time interval for polling listing of the S3 bucket. Defaults to 120s. 

  1. Access Key ID 

  1. Secret Access Key 

If you need further assistance, kindly contact our support at info@cytechint.com for prompt assistance and guidance.

No Comments
Back to top