Cisco Umbrella — Integration Setup

Prerequisites

• Cisco Umbrella subscription (DNS Security Advantage or higher — Reporting v2 API required)
• Umbrella Full Admin or Read-only Admin role
• CMDash Essentials tier or above

How authentication works

Cisco Umbrella connects with an OAuth 2.0 client-credentials pair (Key ID + Secret) from an API key you create in your own Umbrella dashboard. The connection stores that pair: the Key ID as a plain setting and the secret encrypted (never shown again, erased when you disconnect). CMDash never uses one shared Umbrella key for several organizations.

• CMDash Cloud (hosted): you enter your own Key ID and Secret on the connection (Step 2).
• Self-hosted on a licensed install (on-prem / customer-AWS): you may enter them on the connection too; a connection made before this change that has none keeps using the deployment's UMBRELLA_CLIENT_ID / UMBRELLA_CLIENT_SECRET, and only on those installs.

Step 1: Create Umbrella API Credentials (Umbrella admin)

1. Log in to the Umbrella Dashboard.
2. Go to Admin → API Keys (new KeyAdmin UI).
3. Click Add → Umbrella API.
4. Scope: Reports → select Read-only.
5. Expiration: 90 days (rotate before expiry).
6. Copy the Key ID and Secret (the secret is shown once).

Step 2: Connect in CMDash

1. Navigate to Integrations in your CMDash dashboard.
2. Find Cisco Umbrella and click Connect.
3. Enter the API client ID (the Key ID) and API client secret from Step 1, then click Connect. To revoke access, delete the API key in the Umbrella dashboard (and disconnect here, which erases the stored secret).

CMDash exchanges your key + secret for a short-lived OAuth2 bearer token at POST /auth/v2/token, then re-uses it until expiry (~60 minutes).

What Syncs

Each blocked-DNS record becomes a NormalizedIncident with severity mapped from the Umbrella category labels:

• command-and-control, malware, phishing → critical
• botnet, exploit kits → high
• newly seen domains, suspicious domains → medium
• everything else → low

Troubleshooting

• HTTP 401 on token exchange: the Key ID or Secret is wrong or was revoked, or the key was created under the wrong scope (Management instead of Reports).
• HTTP 429 on /reports/v2/activity/dns: Umbrella Reporting v2 rate-limits at 5 requests per second per organization. CMDash reads blocked events 1000 per request using the limit and offset parameters, continuing until a short page, so a busy tenant may brush the limit — the adapter will back off and retry. A hard ceiling of 50,000 events per sync bounds the walk; if it is reached, or a later page fails, the sync is shown as Partial with a warning rather than Healthy.
• No blocked events visible in CMDash: confirm you have at least one Umbrella policy actively blocking categories. If everything is set to "warn" or "monitor", there is no blocked-event traffic to ingest.