> ## 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.

# Microsoft Sentinel Integration

> Connect Cotool to Microsoft Sentinel for KQL log search, incident triage, and analytics-rule management

## Overview

The Microsoft Sentinel integration gives Cotool agents access to a Sentinel-enabled Log Analytics workspace through Azure's REST APIs. It provides:

1. **KQL log search** — run Kusto queries against any table in the workspace (`SigninLogs`, `SecurityEvent`, `OfficeActivity`, Defender `Device*` tables, and so on).
2. **Incident triage** — list and read incidents, their alerts, entities, and comments; add comments; update severity, owner, labels, and status; close incidents with a classification.
3. **Analytics rules** — list and read analytics rules, and create or update Scheduled (KQL) rules. Once connected, Cotool also syncs your rules into its detection coverage views.

Cotool authenticates as a **Microsoft Entra app registration** (service principal) using client credentials. Access is granted with a single Azure RBAC role on the resource group that contains your workspace — no Microsoft Graph or Log Analytics API application permissions are required.

## Before you start

You will need:

* Permission to create app registrations in Microsoft Entra ID (for example the **Application Developer** role).
* **Owner** or **User Access Administrator** on the resource group that contains your Sentinel Log Analytics workspace, to assign a role to the app.

Choose the role for Cotool based on what you want agents to be able to do:

| Role                               | What Cotool can do                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| **Microsoft Sentinel Reader**      | Read only: KQL queries, list and read incidents, list and read analytics rules       |
| **Microsoft Sentinel Responder**   | Everything in Reader, plus update, comment on, and close incidents (**recommended**) |
| **Microsoft Sentinel Contributor** | Everything in Responder, plus create and update analytics rules                      |

## Set up Azure

<Steps>
  <Step title="Register an app in Microsoft Entra">
    1. In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID > App registrations > New registration**.
    2. Enter a recognizable **Name** (for example `Cotool`). Leave the account type at the default (single tenant) and leave **Redirect URI** blank.
    3. Click **Register**.
    4. On the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You will paste these into Cotool as **Client ID** and **Tenant ID**.
  </Step>

  <Step title="Create a client secret">
    1. On the app, open **Certificates & secrets > Client secrets > New client secret**.
    2. Enter a description, choose an expiry, and click **Add**.
    3. Copy the secret **Value** immediately. Azure shows it only once, and the **Secret ID** column is not the secret.

    <Note>
      Client secrets expire. Note the expiry date; before then, create a new secret and update it in Cotool under **Platform > Integrations > Microsoft Sentinel > Edit**.
    </Note>
  </Step>

  <Step title="Assign a Microsoft Sentinel role to the app">
    1. In the Azure portal, open the **resource group** that contains your Sentinel Log Analytics workspace.
    2. Select **Access control (IAM) > Add > Add role assignment**.
    3. On the **Role** tab, search for and select **Microsoft Sentinel Responder** (or Reader / Contributor, per the table above), then click **Next**.
    4. On the **Members** tab, set **Assign access to** to **User, group, or service principal**, click **Select members**, search for the app you registered in step 1, and select it.
    5. Click **Review + assign** (twice, if prompted).

    <Note>
      Assign the role on the **resource group**, not just the workspace. Microsoft recommends this for Sentinel, and it ensures the role covers both incident/rule operations and KQL queries. New role assignments can take a few minutes to take effect.
    </Note>
  </Step>

  <Step title="Copy the workspace details">
    1. In the Azure portal, open **Microsoft Sentinel** and select your workspace, then go to **Settings > Workspace settings**. This opens the underlying Log Analytics workspace. (You can also go directly to **Log Analytics workspaces** and select the workspace.)
    2. On the workspace **Overview** page, copy:
       * **Subscription ID**
       * **Resource group**
       * **Workspace name** — the resource name shown as the page title
       * **Workspace ID** — a GUID, distinct from the Subscription ID
  </Step>
</Steps>

## Connect in Cotool

1. In Cotool, go to **Platform > Integrations > Microsoft Sentinel** and click **Connect**.
2. Enter the values you collected:

| Cotool field    | Where it comes from                                                                          |
| --------------- | -------------------------------------------------------------------------------------------- |
| Tenant ID       | **Directory (tenant) ID** on the app registration Overview page (step 1)                     |
| Client ID       | **Application (client) ID** on the app registration Overview page (step 1)                   |
| Client secret   | The secret **Value** copied when you created it (step 2)                                     |
| Subscription ID | Log Analytics workspace Overview page (step 4)                                               |
| Resource group  | Log Analytics workspace Overview page (step 4); the group you assigned the role on in step 3 |
| Workspace name  | Log Analytics workspace resource name (step 4)                                               |
| Workspace ID    | The **Workspace ID** GUID on the workspace Overview page (step 4)                            |

3. Click **Connect**.

After connecting, Cotool schedules a job that maps the workspace's tables and analytics rules so agents know which data sources are available.

## Troubleshooting

* **HTTP 401 / 403 on any action** — confirm the role assignment from step 3 is on the correct resource group and targets the app (not a user), wait a few minutes for it to propagate, and confirm the client secret has not expired.
* **HTTP 404** — double-check the Subscription ID, Resource group, and Workspace name; the Workspace name must be the Azure resource name, not a friendly display name.
* **KQL queries fail but incidents work** — the Workspace ID is wrong (it is the GUID on the workspace Overview page, not the Subscription ID).
* **Reads work but incident updates or rule writes fail with 403** — the app's role is too low. Incident changes need **Microsoft Sentinel Responder**; creating or updating analytics rules needs **Microsoft Sentinel Contributor**.

## Local development

Populate `cogent-backend/.env` with `MICROSOFT_SENTINEL_TENANT_ID`, `MICROSOFT_SENTINEL_CLIENT_ID`, `MICROSOFT_SENTINEL_CLIENT_SECRET`, `MICROSOFT_SENTINEL_SUBSCRIPTION_ID`, `MICROSOFT_SENTINEL_RESOURCE_GROUP`, `MICROSOFT_SENTINEL_WORKSPACE_NAME`, and `MICROSOFT_SENTINEL_WORKSPACE_ID`, then run `npm run bootstrap-tools <API_KEY>` from the repo root.