> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cisco Umbrella

> Connect Cisco Umbrella to Myrmex with an Umbrella API key and secret — create them and add the integration.

import { Note, Steps, Step, CardGroup, Card, Tip } from '@mintlify/components';

Connect **Cisco Umbrella** so Myrmex can read your DNS-layer security data in real time — activity, top domains, and blocked or flagged requests — for investigation and analysis. Myrmex connects over the **Umbrella API** (`api.umbrella.com`) using an API key and secret (OAuth 2.0 client credentials).

## What Myrmex Can Do

<CardGroup cols={2}>
  <Card title="DNS security visibility" icon="shield-halved">
    Read DNS-layer activity, security events, and blocked requests, on demand.
  </Card>

  <Card title="Investigate domains" icon="magnifying-glass">
    Pull top domains and identities into investigations in the Workspace.
  </Card>

  <Card title="Analyze activity" icon="chart-line">
    Query DNS activity in real time to support your analyses.
  </Card>

  <Card title="Correlate" icon="diagram-project">
    Cross-reference DNS events with data from your other integrations.
  </Card>
</CardGroup>

## Before You Start

* A **Cisco Umbrella** account with dashboard access.
* Permission to create **API Keys** in the Umbrella dashboard (**Admin → API Keys**).
* The scopes appropriate for what Myrmex should read (read scopes such as Reports are enough for analysis).

## Step 1 — Create the API Key in Cisco Umbrella

<Steps>
  <Step title="Open API Keys">
    In the Umbrella dashboard, go to **Admin → API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Add** to create a new key, name it, and select the scopes Myrmex needs (read scopes are enough for analysis).
  </Step>

  <Step title="Copy the key and secret">
    Copy the **API Key** and **Key Secret**. The secret is shown only once — store it securely. You'll enter both in Myrmex.
  </Step>
</Steps>

## Step 2 — Add the Integration in Myrmex

From the **Directory**, choose **Add Integration → Cisco Umbrella**, then fill in:

| Field                     | Description                                                                                              |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Name**                  | A unique name for this Umbrella organization.                                                            |
| **Description**           | Optional note to identify it.                                                                            |
| **Username (API Key)**    | The Umbrella API Key from Step 1.                                                                        |
| **Password (Key Secret)** | The matching Key Secret.                                                                                 |
| **Host**                  | The Umbrella API host (default `api.umbrella.com`).                                                      |
| **Port**                  | The HTTPS port (default `443`).                                                                          |
| **Collector**             | Optional [Collector](/documentation/agent-endpoint-security/collector-mode) to route the API connection. |

## Connect

Click **Connect**. Myrmex requests an access token from the Umbrella token endpoint (`/auth/v2/token`) using your key and secret, validates the connection, and finishes. Umbrella then appears under **Environment → Integrations**.

<Note>
  Myrmex handles the OAuth 2.0 client-credentials exchange for you — you only supply the API Key and Key Secret. Data is read in real time when you ask; nothing from Umbrella is stored on the Myrmex side.
</Note>