# NG SIEM - CISCO Umbrella Integration
##### **Introduction**
Cisco Umbrella is a cloud-delivered security platform that provides an additional layer of defense against malicious threats on the internet using Cisco’s threat intelligence. It helps block access to:
- **Malware**
- **Adware**
- **Botnets**
- **Phishing attacks**
- **Known malicious websites**
##### **Assumptions**
The procedures described in this guide assume that a Log Collector has already been set up.
##### **Prerequisites**
- Full Admin access to Cisco Umbrella to create and manage Umbrella API keys.
- Umbrella API KeyAdmin access (if managing API key scopes and expirations).
---
##### **Requirements**
**This integration supports log ingestion from Cisco Umbrella. Data is collected from:**
- AWS S3 buckets using an SQS notification queue
- Cisco-managed S3 buckets without SQS
##### **Supported Dataset**
- log dataset: Collects Cisco Umbrella logs.
---
##### **Umbrella Logs**
**When using Cisco-managed S3 buckets without SQS:**
- Load balancing across multiple agents is not supported.
- A single agent must be configured to poll the S3 bucket.
- Vertical scaling can be applied by configuring the number of workers.
**The log dataset is responsible for collecting all Cisco Umbrella logs.**
---
##### **Advantages of the Umbrella API Integration**
**The Umbrella API introduces several improvements over older versions (v1 and Reporting v2 APIs):**
- Intuitive base URI
- API paths defined by top-level scopes
- Granular, intent-based API key scopes
- API key expiration support
- Updated API administration dashboard
- Programmatic API key administration
- Authentication & authorization via OAuth 2.0 client credentials flow
- Portable, programmable API interface for integrations
**Before sending requests to the Umbrella API, create Umbrella API credentials and generate an access token.**
**More details: [Cisco Umbrella API Authentication](https://developer.cisco.com/docs/cloud-security/authentication/#authentication)**
---
##### **Authentication**
- The Umbrella API provides a **REST interface**.
- Supports **OAuth 2.0 client credentials flow**.
**Steps:**
1. Log in to Umbrella at: **[https://dashboard.umbrella.com](https://dashboard.umbrella.com/)**
2. Create a new **API Key (ID + Secret)**.
- Keys can only be copied once at creation.
- Lost secrets cannot be retrieved.
3. Generate an **API Access Token** using your credentials.
**Important:** API keys, passwords, and tokens grant access to private customer data. **Never share them** with external users or organizations.
---
##### **Managing Umbrella API Keys**
**Create a New API Key**
1. Navigate to **Admin > API Keys**
- For MSP/MSSP: **Console Settings > API Keys**
2. Click **Add Key**.
3. Enter a **Name** (≤256 characters) and optional **Description**.
4. Select **Scopes** (Read-Only or Read/Write).
5. Configure an **Expiry Date** (or select *Never Expire*).
6. (Optional) Add **Network Restrictions** (up to 10 public IPs or CIDRs).
7. Click **Create Key** → Copy and save **Key + Secret**.
**Refresh an API Key**
1. Go to **Admin > API Keys**.
2. Expand the target key → Click **Refresh Key**.
3. Copy and save the new **Key + Secret**.
**Update an API Key**
1. Expand an existing key.
2. Update **Name, Description, Scopes, Expiry, or Network Restrictions**.
3. Click **Save**.
---
To integrate Cisco Umbrella logs into AQUILA, provide the following details to **CyTech Support**:
- **Queue URL**
- AWS SQS queue URL where messages will be received.
- For Cisco-managed S3 without SQS, use **Bucket ARN** instead.
- **Bucket ARN**
- Required for Cisco-managed S3.
- Example: `arn:aws:s3:::cisco-managed-eu-central-1`
- **[List of Cisco-managed S3 buckets](https://docs.umbrella.com/mssp-deployment/docs/enable-logging-to-a-cisco-managed-s3-bucket)**
- **Bucket Region**
- The AWS region where the bucket is located.
- **Bucket List Prefix**
- The root folder of the S3 bucket to be monitored (visible in the S3 UI).
- Example: `1235_654vcasd23431e5dd6f7fsad457sdf1fd5`
- **Number of Workers**
- Number of workers to process S3 objects (min = 1).
- **Bucket List Interval**
- Time interval for polling the S3 bucket. Default = 120s.
- **Access Key ID**
- **Secret Access Key**
*If you need further assistance, kindly contact **support@cytechint.com** for prompt assistance and guidance.*