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

# Azure Event Hub Integration

> Stream Azure Activity Logs, resource diagnostic logs, Entra ID diagnostic logs, and Defender for Cloud alerts into Cotool Logs

The Azure Event Hub integration continuously ingests Azure platform logs into Cotool Logs. Azure Event Hubs is Microsoft's designated export path for third-party security tooling: you point Azure diagnostic settings (and Defender for Cloud Continuous Export) at an event hub in your tenant, and Cotool consumes the hub and indexes the events into queryable, tenant-isolated warehouse tables.

## What gets ingested

The integration exposes four independently toggleable log streams:

| Stream                    | Cotool Logs table       | Contents                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activity Log              | `azure_activity`        | Subscription control-plane audit events (role assignments, resource writes/deletes, key listings, policy and security events) exported through a subscription-level diagnostic setting.                                                                                                                                                                    |
| Resource logs             | `azure_resource_logs`   | Data-plane diagnostic logs: Azure Firewall, Application Gateway and Front Door WAF/access logs, AKS control-plane logs (`kube-audit`), PostgreSQL Flexible Server, Storage, Key Vault, Container Registry, and Azure OpenAI / Cognitive Services. Categories Cotool does not yet model land in the same table as passthrough rows — data is never dropped. |
| Entra ID diagnostic logs  | `azure_entra_logs`      | Tenant-level Microsoft Entra ID categories, primarily the ones not available through the Graph reporting API: `MicrosoftGraphActivityLogs` and `EnrichedOffice365AuditLogs`.                                                                                                                                                                               |
| Defender for Cloud alerts | `azure_defender_alerts` | Security alerts streamed through Defender for Cloud Continuous Export.                                                                                                                                                                                                                                                                                     |

<Note>
  Every ingested event is archived in full before indexing, and each table
  keeps the complete provider record in `raw_payload`, so nothing is lost to
  normalization.
</Note>

## Step 1: Create the event hub

1. Create (or reuse) an **Event Hubs namespace** in your tenant. A Standard-tier namespace with 1 throughput unit and auto-inflate enabled is a good starting point.
2. Create an event hub with **4 partitions** and **7-day retention**. Retention is your replay buffer: if ingest is ever paused longer than the retention window, the overflow is unrecoverable.
3. You can point every log source at a single hub — Cotool routes each record by its content, not by which hub it arrived on — or use one hub per source. If you let Azure Monitor create hubs automatically it makes one per category (`insights-logs-<category>`); listing them all in Cotool works, but a single explicit hub is simpler.

<Warning>
  Diagnostic settings can only stream to an event hub **in the same region**
  as the resource. Multi-region estates need one hub (or namespace) per
  region; list them all when connecting.
</Warning>

Optionally create a dedicated **consumer group** named `cotool` on each hub. The default `$Default` group works, but a dedicated group is required if another tool already reads the same hub.

## Step 2: Point your log sources at the hub

* **Activity Log**: in the Azure portal, go to **Monitor → Activity log → Export Activity Logs**, add a diagnostic setting on each subscription, select the categories you want (at minimum `Administrative`, `Security`, and `Policy`), and stream to the event hub.
* **Resource logs**: on each resource (Firewall, Application Gateway, AKS cluster, PostgreSQL flexible server, storage account service, key vault, container registry, Azure OpenAI account), add a **diagnostic setting** that streams the desired log categories to the event hub. For AKS, `kube-audit-admin` is a lower-volume alternative to `kube-audit` that omits get/list reads.
* **Entra ID**: in the Entra admin center, go to **Monitoring & health → Diagnostic settings** (requires Security Administrator) and stream the desired categories. The namespace must be in a subscription associated with the Entra tenant.
* **Defender for Cloud**: in **Environment settings → your subscription → Continuous export**, enable export of **Security alerts** to the event hub (Azure Policy can roll this out at scale).

### Licensing caveats

* `MicrosoftGraphActivityLogs` requires **Microsoft Entra ID P1 or P2** and is high volume (roughly 60k events per month per 1,000 users).
* `EnrichedOffice365AuditLogs` requires **Global Secure Access (Internet Access) licensing** with the Microsoft traffic forwarding profile enabled, and currently covers **SharePoint Online only**. It does not replace a general Microsoft 365 audit connector.
* Entra sign-in log exports require Entra ID P1/P2. Sign-in and audit categories streamed to the hub are ingested as passthrough rows in `azure_entra_logs`; if you also use the Microsoft Graph Admin integration's Entra log ingest, the same events will exist in both the `entra` and `azure_entra_logs` tables.

## Step 3: Grant Cotool access

Choose one of two authentication modes.

### Option A: User-assigned managed identity (recommended)

This mode uses workload identity federation — no secret is ever created or stored.

1. Create a **user-assigned managed identity** in your tenant (e.g. `cotool-log-ingest`).
2. On the Event Hubs **namespace** (or narrower scope), assign the identity the **Azure Event Hubs Data Receiver** role.
3. On the managed identity, open **Federated credentials → Add credential → Other issuer** and enter:
   * **Issuer**: `https://accounts.google.com`
   * **Subject identifier**: the value shown on the Cotool connect form (the unique ID of Cotool's deployment service account)
   * **Audience**: `api://AzureADTokenExchange`
4. In Cotool, connect the **Azure Event Hub** integration with your **tenant ID**, the managed identity's **client ID**, and the event hub list.

At runtime Cotool exchanges its own cloud identity token for an Entra token as your managed identity, scoped to Event Hubs. You can revoke access at any time by deleting the federated credential or the role assignment.

### Option B: SAS connection string

1. On the Event Hubs **namespace**, create a shared access policy with only the **Listen** claim (a namespace-scoped policy covers every hub in the namespace).
2. Paste the policy's primary connection string into the Cotool connect form along with the event hub list.

The connection string is stored in Cotool's encrypted secret store and never returned by the API.

## Step 4: Connect and enable streams

1. In Cotool, go to **Settings → Integrations → Azure Event Hub**.
2. Enter the event hubs as `<namespace FQDN>/<hub name>` entries (one per line), e.g. `contoso.servicebus.windows.net/insights-logs`, plus the credentials from Step 3 and the consumer group if you created one.
3. Cotool validates access to each hub before saving. A missing role assignment or bad SAS policy blocks the save with the provider error; a transient network failure does not.
4. On the integration page, enable the log streams you configured in Step 2. Ingest starts within a few minutes and consumes each hub partition from the start of its retained buffer.

## How ingest works

* Cotool polls every hub partition on a fixed schedule and drains it from the last durably indexed position (Event Hub sequence numbers). There is no checkpoint container in your storage account — resume positions live in Cotool.
* Delivery is at-least-once; the warehouse deduplicates on the hub position, so replays never create duplicate rows.
* Each run reports per-partition lag (partition head minus indexed position) in the ingest run history on the Log Ingest page. Status rows on the integration page are per hub partition (shown as `<hub name> · partition <n>`), not per enabled log stream — every partition carries a mix of the streams routed through the hub.
* Ingest requires outbound AMQP (TCP 5671) from Cotool to `<namespace>.servicebus.windows.net`; no inbound connectivity to your tenant is needed.