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

# Microsoft Sentinel

> Bi-directional integration between CaseBender and Microsoft Sentinel for incident ingestion (pull or push) and disposition sync.

## Overview

The Microsoft Sentinel integration (**INT-009**) ingests Sentinel incidents into CaseBender and
can push case dispositions back to Sentinel when a case is closed.

<CardGroup cols={2}>
  <Card title="Inbound Ingestion" icon="arrow-right-to-bracket">
    Sentinel incidents are ingested — either **pulled automatically** on a
    schedule (recommended) or **pushed** via a webhook / Logic App — then
    normalized and turned into alerts.
  </Card>

  <Card title="Outbound Disposition Sync" icon="arrow-right-from-bracket">
    When a linked CaseBender case is closed, the Sentinel incident status and
    classification are updated with an audit comment.
  </Card>
</CardGroup>

<Tip>
  **Recommended: enable Automatic polling.** CaseBender can pull new incidents on
  a schedule directly from your Log Analytics workspace — no Logic App, data
  connector, or inbound endpoint is required. See
  [Automatic polling](#inbound-automatic-polling-recommended).
</Tip>

<Note>
  This integration uses the **Azure Security Insights REST API** and
  authenticates with an **Azure AD (Entra ID) application** using the OAuth2
  client-credentials flow (scope `management.azure.com`).
</Note>

## Capabilities

| Capability                     | Direction      | Description                                                                                      |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------ |
| **Incident polling (pull)**    | Inbound        | CaseBender polls the Security Insights API on a schedule and ingests new incidents automatically |
| Incident ingestion (push)      | Inbound        | Sentinel incidents are pushed via webhook / Logic App                                            |
| Observable & entity extraction | Inbound        | Entities are extracted from the incident                                                         |
| Disposition sync               | Outbound       | Incident `status` + `classification` + comment are pushed on case close                          |
| Connection test                | Bi-directional | Validates OAuth2 credentials and workspace access                                                |

## Prerequisites

<Steps>
  <Step title="Register an Azure AD application">
    In the [Microsoft Entra admin center](https://entra.microsoft.com), register an app and
    create a **client secret**. Record the **Directory (tenant) ID**, **Application (client)
    ID**, and secret value.
  </Step>

  <Step title="Assign the workspace role">
    Grant the app the **Microsoft Sentinel Reader** role on the Sentinel-enabled Log Analytics
    workspace (for inbound). For outbound close-back, grant **Microsoft Sentinel Responder**.
  </Step>

  <Step title="Collect workspace coordinates">
    Record the **Subscription ID**, **Resource Group**, and **Log Analytics workspace name**.
  </Step>

  <Step title="Network egress">
    The CaseBender poller must reach `login.microsoftonline.com` and `management.azure.com`.
  </Step>
</Steps>

## Configure the integration in CaseBender

<Steps>
  <Step title="Open the integration catalog">
    Go to **Settings → Integrations → Create**, then choose **Microsoft Sentinel** from the
    **SIEM** category.
  </Step>

  <Step title="Enter Azure credentials and workspace">
    | Field                        | Description                                 |
    | ---------------------------- | ------------------------------------------- |
    | Azure Tenant ID              | Directory (tenant) ID                       |
    | Application (Client) ID      | The app registration client ID              |
    | Client Secret                | The client secret value                     |
    | Subscription ID              | Azure subscription containing the workspace |
    | Resource Group               | Resource group of the workspace             |
    | Log Analytics Workspace Name | Sentinel-enabled workspace to poll          |
  </Step>

  <Step title="Enable automatic polling (recommended)">
    | Option                        | Effect                                                                    |
    | ----------------------------- | ------------------------------------------------------------------------- |
    | `pollingEnabled`              | Turn on scheduled pulling of Sentinel incidents                           |
    | `pollingIntervalMinutes`      | How often to poll (default `5`, range 1–1440)                             |
    | `pollingInitialLookbackHours` | On first run, import incidents modified within this window (default `24`) |
    | `pollMaxItemsPerRun`          | Safety cap on items ingested per run (default `500`)                      |
  </Step>

  <Step title="Configure auto-case creation">
    | Option               | Effect                                                                                                                |
    | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
    | `autoCreateCases`    | Promote each ingested incident to a **Case** (deduped by incident name). When off, incidents stay in the Alerts inbox |
    | `minSeverityForCase` | Only auto-create cases at/above this severity                                                                         |
  </Step>
</Steps>

## Inbound (automatic polling, recommended)

<Steps>
  <Step title="Scheduled pull">
    On each interval, CaseBender lists incidents from the workspace with
    `properties/lastModifiedTimeUtc` greater than the last cursor, ordered ascending. On the
    first run, incidents modified within `pollingInitialLookbackHours` are imported.
  </Step>

  <Step title="Cursor + deduplication">
    CaseBender advances a per-integration cursor to the newest `lastModifiedTimeUtc`. Incidents
    are **deduplicated by incident name**, so overlapping polling windows never create
    duplicates.
  </Step>

  <Step title="Normalization">
    Each incident is normalized into a CaseBender alert, and the Sentinel incident identifier is
    preserved so outbound close-sync can find it later.
  </Step>
</Steps>

<Info>
  Polling runs in CaseBender's background poller service. Ensure it can reach
  `login.microsoftonline.com` and `management.azure.com` (directly or via your proxy).
</Info>

## Outbound: syncing case dispositions to Sentinel

When a linked case is closed, CaseBender updates the Sentinel incident `status` (to `Closed`)
and `classification`, and adds an audit comment. Outbound requires the **Microsoft Sentinel
Responder** role.

## Security considerations

* **Least privilege** — grant **Sentinel Reader** for inbound only; add **Sentinel Responder**
  only if you enable outbound close-back.
* **Secret handling** — rotate the client secret on your organization's schedule.
* **Network** — restrict egress to `login.microsoftonline.com` and `management.azure.com`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication fails">
    Verify the tenant/client IDs and secret, and that the app has the Sentinel Reader role on
    the workspace. Confirm the subscription ID, resource group, and workspace name are correct.
  </Accordion>

  <Accordion title="Polling is enabled but no incidents appear">
    Confirm **Enable automatic polling** is on and the workspace coordinates are correct. Check
    the poller can reach `management.azure.com`. On first run only incidents within
    `pollingInitialLookbackHours` are imported.

    **Make sure all CaseBender services are running** — with Docker, `docker compose ps` should
    show the `worker` and `misp-processor` services `Up`.
  </Accordion>

  <Accordion title="Case close doesn't update Sentinel">
    Ensure the app has the Sentinel Responder role and the case is linked to a Sentinel
    incident. Check the case timeline for the sync result.
  </Accordion>
</AccordionGroup>

## Related documentation

* [Integrations overview](./introduction.mdx)
* [Microsoft Sentinel REST API](https://learn.microsoft.com/en-us/rest/api/securityinsights/)