Connect Qevlar to Microsoft Defender to investigate Defender incidents and run advanced-hunting queries across the Microsoft Defender stack. This page lists the Microsoft Graph permissions Qevlar requires and how to grant them.
Overview
Qevlar authenticates as an Entra ID (Azure AD) app registration using the OAuth 2.0 client credentials flow — no user account or interactive sign-in. Authorization is granted through Microsoft Graph application permissions, which require tenant admin consent. The connector is read-only.
| API | Purpose | Token audience |
|---|---|---|
| Microsoft Graph | Read incidents and alerts, run advanced-hunting queries, read email content | https://graph.microsoft.com |
Tokens are issued by https://login.microsoftonline.com/{tenantId}/oauth2/token.
Connection details
Enter these values when configuring the connector in Qevlar:
| Field | Where to find it | Required |
|---|---|---|
| Tenant ID | Entra ID → Overview | Yes |
| Client ID | App registration → Overview | Yes |
| Client Secret | App registration → Certificates & secrets | Yes |
Required permissions
Grant these as Microsoft Graph application permissions (not delegated) on the app registration, then grant admin consent for the tenant. All four require admin consent to take effect.
| Permission | Grants |
|---|---|
| ThreatHunting.Read.All | Run advanced-hunting (KQL) queries across the Defender stack. Required — the connector does not start without it. |
| SecurityIncident.Read.All | Read the Defender incident that triggered an investigation |
| SecurityAlert.Read.All | Read the alerts attached to an incident |
| Mail.Read | Recommended — not required for the connector to start. Read mailbox content for Microsoft Defender for Office 365 email / phishing investigations. |
Mail.Read grants read access to all mailboxes. To restrict it, apply an Exchange Online application access policy scoping the app to specific mailboxes; Qevlar works correctly as long as the mailboxes referenced in alerts are in scope.
These permissions cover the Defender products Qevlar reads:
| Defender product | Powered by |
|---|---|
| Defender for Endpoint | ThreatHunting.Read.All |
| Defender XDR | ThreatHunting.Read.All, SecurityIncident.Read.All, SecurityAlert.Read.All |
| Defender for Cloud Apps | ThreatHunting.Read.All |
| Defender for Identity | ThreatHunting.Read.All |
| Defender for Office 365 | ThreatHunting.Read.All, Mail.Read |
Setup
-
Create the app registration. Entra ID → App registrations → New registration. Name it (for example
qevlar-defender-connector); no redirect URI is needed. Record the Client ID and Tenant ID from the Overview page. - Create a client secret. App registration → Certificates & secrets → New client secret. Copy the secret value immediately — it is shown only once. Note its expiry and plan to rotate it before it lapses.
- Add API permissions. App registration → API permissions → Add a permission → Microsoft Graph → Application permissions. Add ThreatHunting.Read.All, SecurityIncident.Read.All, SecurityAlert.Read.All, and Mail.Read.
- Grant admin consent. Select Grant admin consent for your tenant, then confirm each permission shows a green "Granted" status.
- Configure the connector. In Qevlar, add the Microsoft Defender connector and enter the connection details above.
Verify the connection
After saving, Qevlar runs a health check that acquires a Microsoft Graph token and inspects its permissions. If it fails, check, in order:
- Admin consent was granted — not just added. Permissions added without consent do not appear in the token.
- The permissions are Application type, not Delegated.
- The client secret value is correct and not expired.
- Consent can take a few minutes to propagate after granting.
API reference
| Operation | HTTP | Endpoint | Permission |
|---|---|---|---|
| Read incident and alerts | GET | graph.microsoft.com/v1.0/security/incidents/{id}?$expand=alerts |
SecurityIncident.Read.All, SecurityAlert.Read.All |
| Run hunting query | POST | graph.microsoft.com/v1.0/security/runHuntingQuery |
ThreatHunting.Read.All |
| Read mail | GET | graph.microsoft.com/v1.0/users/{id}/messages |
Mail.Read |
Token endpoint: https://login.microsoftonline.com/{tenantId}/oauth2/token · resource https://graph.microsoft.com.