Skip to main content

​
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:

​
Set up Azure

1

Register an app in Microsoft Entra

  1. In the Azure portal, 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.
2

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.
Client secrets expire. Note the expiry date; before then, create a new secret and update it in Cotool under Platform > Integrations > Microsoft Sentinel > Edit.
3

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).
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.
4

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

​
Connect in Cotool

  1. In Cotool, go to Platform > Integrations > Microsoft Sentinel and click Connect.
  2. Enter the values you collected:
  1. 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.