# Microsoft Sentinel Integration

Forward Capsule Security alerts into Microsoft Sentinel so your SOC can triage AI agent and shadow-AI signals alongside the rest of your security telemetry.

## Overview

Unlike Capsule's discovery integrations, this is an **outbound** integration: Capsule sends policy-violation alerts *into* your Microsoft Sentinel workspace rather than reading data out of it. Delivery uses the **Azure Monitor Logs Ingestion API**, writing each alert as a row in a custom Log Analytics table (`CapsuleAlert_CL`) on your Sentinel-enabled workspace. From there, your existing Sentinel analytics rules and incident workflows can act on Capsule alerts.

Capsule authenticates as an approved **Microsoft Entra ID** application using the client-credentials flow. The application is granted a single, narrowly scoped Azure role on the data collection rule — it cannot read your workspace, query data, or access anything else in your tenant.


```
Capsule policy violation
  → Capsule sends to your Data Collection Endpoint
  → Data Collection Rule routes the record
  → CapsuleAlert_CL table in your Log Analytics workspace
  → Microsoft Sentinel analytics rules / incidents
```

## Prerequisites

Before you begin, ensure you have:

- **Microsoft Sentinel** enabled on a Log Analytics workspace
- Azure permissions to create a Data Collection Endpoint, a Data Collection Rule, and a custom table — typically **Monitoring Contributor** (or **Contributor**) on the resource group
- The ability to assign Azure RBAC roles on the data collection rule — **User Access Administrator** or **Owner**
- A **Microsoft Entra ID** account with **Application Administrator** or **Global Administrator** role (to grant admin consent to the Capsule application)
- A **Capsule Security** account with admin access


## Step 1: Create the Custom Table

In your Sentinel-enabled Log Analytics workspace, create a custom table named `CapsuleAlert_CL` with the schema below. The Logs Ingestion API requires a `TimeGenerated` column of type `datetime`.

| Column | Type | Description |
|  --- | --- | --- |
| `TimeGenerated` | datetime | When the violation occurred |
| `Title` | string | Alert title |
| `Description` | string | Alert detail |
| `Severity` | string | `Informational`, `Low`, `Medium`, or `High` |
| `PolicyName` | string | The Capsule policy that triggered the alert |
| `EntityName` | string | The affected agent or resource |
| `SourceUrl` | string | Deep link back into the Capsule portal |
| `TenantId` | string | Your Capsule tenant identifier |
| `PolicyId` | string | Capsule policy identifier |
| `EntityId` | string | Capsule entity identifier |
| `IssueId` | string | Capsule issue identifier |
| `AdditionalContext` | dynamic | Remaining alert metadata as JSON |


## Step 2: Create a Data Collection Endpoint

Create a **Data Collection Endpoint (DCE)** in the same region as your workspace. After creation, record its **Logs Ingestion URI** — Capsule sends alerts to this address.

## Step 3: Create a Data Collection Rule

Create a **Data Collection Rule (DCR)** that validates incoming alerts and routes them to the custom table.

1. Associate the DCR with the endpoint from Step 2.
2. Define an input stream named **`Custom-CapsuleAlert_CL`** using the schema from Step 1.
3. Set the destination to your Log Analytics workspace, output table `CapsuleAlert_CL`.
4. A pass-through transformation (`source`) is sufficient unless you want to reshape rows.


After creation, record the DCR's **immutable ID** (for example, `dcr-xxxxxxxxxxxxxxxx`).

## Step 4: Grant Admin Consent and Assign Permissions

Authorize the Capsule application and grant it the single role it needs to publish alerts.

### Grant admin consent

1. Sign in with your Microsoft Entra ID account that has the required administrator role (see Prerequisites).
2. Review the access requested by the Capsule application.
3. Click **Accept** to grant admin consent for your organization. This creates the Capsule application's service principal in your tenant.


### Assign the publishing role

Assign the following Azure RBAC role to the Capsule application's service principal, scoped to the **data collection rule** from Step 3:

| Role | Role definition ID | Scope |
|  --- | --- | --- |
| **Monitoring Metrics Publisher** | `3913510d-42f4-4e42-8a64-420c390055eb` | The data collection rule (DCR) |


This is the only permission Capsule requires:

- **No Microsoft Graph permissions are needed.** Log ingestion uses the Azure Monitor data plane (`https://monitor.azure.com`), not Microsoft Graph — so the application requests no mailbox, directory, or device permissions.
- Scope the role to the **DCR**, not the subscription. Following least privilege, the Monitoring Metrics Publisher role only allows Capsule to publish records through that rule; it cannot read your workspace or query any data.


Allow a few minutes for the role assignment to propagate before testing.

## Step 5: Configure the Integration in Capsule

1. Log in to the **Capsule Security** portal.
2. Go to **Settings > Notifications**.
3. Find **Microsoft Sentinel** and click **Set up**.
4. Enter the connection values:
| Field | Where it comes from |
|  --- | --- |
| Data Collection Endpoint URI | DCE Logs Ingestion URI (Step 2) |
| DCR immutable ID | DCR immutable ID (Step 3) |
| Stream name | `Custom-CapsuleAlert_CL` (Step 3) |
5. Click **Test Connection**. Capsule posts a synthetic record to the stream; success confirms the endpoint, rule, stream, and role assignment are all correct.
6. Link the Sentinel destination to the policies whose violations you want forwarded.


## After Setup

Once configured, Capsule forwards alerts for linked policies as they occur. To confirm records are arriving, run this query in your workspace:


```kql
CapsuleAlert_CL
| sort by TimeGenerated desc
| take 20
```

Ingestion latency is typically a few minutes for a newly created custom table. From here, build Sentinel analytics rules on `CapsuleAlert_CL` to raise incidents from Capsule alerts.

## Troubleshooting

### Common Issues

1. **`403 Forbidden` when sending alerts**
  - The Monitoring Metrics Publisher role is not assigned to the Capsule service principal on this DCR, or the assignment hasn't propagated yet.
2. **`404 Not Found` when sending alerts**
  - The DCR immutable ID or stream name is incorrect, or the DCR isn't associated with the data collection endpoint.
3. **`401 Unauthorized`**
  - Confirm admin consent was granted so the Capsule service principal exists in your tenant.
4. **Test passes, but no rows appear in `CapsuleAlert_CL`**
  - The stream schema doesn't match the table columns, or the DCR transformation is dropping rows. Review the DCR transform and the table schema from Step 1.


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, Entra tenant ID, Log Analytics workspace ID, and any error messages


## References

- [Logs Ingestion API in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/logs-ingestion-api-overview)
- [Data collection endpoints](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-endpoint-overview)
- [Data collection rules](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview)
- [Monitoring Metrics Publisher built-in role](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#monitoring-metrics-publisher)
- [Grant admin consent to applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)