Skip to content

MSEntraID#

README

Microsoft Entra ID / Azure AD Analyzers#

This repository provides a set of Cortex analyzers to enrich your investigations in TheHive with data from Microsoft Entra ID (Azure AD). All analyzers use the Microsoft Graph API for data retrieval. Each analyzer requires an Azure AD app registration (client ID + secret) with admin-consented permissions (OAuth2 scopes).

Table of Contents#

  1. Overview of Analyzers
  2. Global Configuration
  3. Setup
    - Prereqs
    - Steps
  4. Analyzers
    - getSignIns / Microsoft Entra ID Sign In Retriever
    - getUserInfo
    - getDirectoryAuditLogs
    - getManagedDevicesInfo
    - getDirectoryRoles
    - getSignInsByIP
    - getRiskyUser (requires Entra ID P1/P2)
  5. Customization
  6. General Notes on Permissions
  7. References

Overview of Analyzers#

These analyzers provide useful context for Incident Response teams, such as:

  • Sign-in logs (location, risk, IP, etc.), by user or by source IP address
  • User profile details (manager, licenses, groups, MFA methods)
  • Directory audit logs (object changes in Azure AD)
  • Intune-managed devices (compliance, OS, last sync)
  • Directory role assignments (is this user a privileged/admin account?)
  • Identity Protection risk signals (current risk state and risk detection history)

Global Configuration#

All analyzers share these config fields:

  • client_id: Application (client) ID of your Azure AD app registration
  • client_secret: Client Secret generated for that app
  • tenant_id: Azure AD Tenant ID
  • service: Which analyzer action to run, hardcoded (such as getSignIns, getUserInfo, getDirectoryAuditLogs, getManagedDevicesInfo, getDirectoryRoles, getSignInsByIP, getRiskyUser)

Additional parameters (such as lookup_range, lookup_limit, state, country) appear in certain analyzers. They allow you to define:

  • Time range (how far back to query logs)
  • Max results (number of records to retrieve)
  • Location-based taxonomies (flag sign-ins from out-of-state/country)

Setup#

Prereqs#

  • A user account with at least the Cloud Application Administrator role to create and manage app registrations.
  • A user account with the Global Administrator role to grant admin consent to the required API permissions.

Steps#

1. Creation#

  1. Navigate to the Microsoft Entra ID Portal and sign in with an administrator account.
  2. Go to App Registrations and create a new registration.
  3. Provide a display name (any name you want, can be changed later). Click Register.

2. Secret#

  1. Under Certificates & secrets, create a new client secret.
  2. Enter a relevant description and set an appropriate expiration date.
  3. Copy the Value. This will only be fully visible once, so store it in a safe place right away.

3. API Permissions#

  1. Go to API permissions.
  2. Add the relevant permissions depending on which analyzers you plan to use, for example:
  3. Directory.Read.All
  4. AuditLog.Read.All
  5. DeviceManagementManagedDevices.Read.All (Intune analyzers)
  6. UserAuthenticationMethod.Read.All (if fetching MFA)
  7. IdentityRiskyUser.Read.All (getRiskyUser — current risk state, requires Entra ID P2)
  8. IdentityRiskEvent.Read.All (getRiskyUser — risk detection history, requires Entra ID P1/P2)
  9. For each Application permission, use a Global Administrator account to Grant admin consent.
  10. Copy your Tenant ID, Application (Client) ID, and the Client Secret into the analyzer configuration in Cortex.

Analyzers#

getSignIns / Microsoft Entra ID Sign In Retriever#

Purpose
Retrieves recent sign-in logs for a user (by UPN). Shows IP address, client app used, resource name, location, risk level, etc.

Key Points
- Graph Endpoint
- GET /auditLogs/signIns
- Filters sign-ins by user principal name (startswith(userPrincipalName,'xxx')) and time range.
- You can specify a state and country; sign-ins from outside these will be flagged in taxonomies.

Required Permissions

  • AuditLog.Read.All (Application permission)

Example Configuration

  • lookup_range = 7 (past 7 days)
  • lookup_limit = 50
  • state = "New York" (to flag out-of-state sign-ins)
  • country = "US" (to flag out-of-country sign-ins)

Sample Usage

  • Run on TheHive’s observable of type mail
  • Analyzer returns sign-ins from the last 7 days, up to 50 entries.

getUserInfo#

Purpose
Enriches context around a user with user profile details from Microsoft Entra ID: display name, job title, department, licenses, manager, group memberships, optional MFA methods.

Key Points
- Graph Endpoints
- GET /users/{id}
- GET /users/{id}/manager
- GET /users/{id}/licenseDetails
- GET /users/{id}/memberOf
- (Optional) GET /users/{id}/authentication/methods for MFA.

Required Permissions
- Directory.Read.All or User.Read.All for user properties & group membership.
- UserAuthenticationMethod.Read.All if retrieving MFA methods. - AuditLog.Read.All is required if you add signInActivity to params_list to populate lastSignInDateTime (not in the default list). ⚠️ Selecting it without this permission makes the entire /users request fail with a 403, not just that field — only add it if you're sure the permission is granted.

Sample Usage

  • Run on TheHive’s observable of type mail
  • Returns extensive user info, including manager info, assigned licenses, group memberships, etc.

getDirectoryAuditLogs#

Purpose
Retrieves Directory Audit records—administrative and policy changes made within Azure AD (such as user updates, group changes, role assignments).

Key Points
- Graph Endpoint
- GET /auditLogs/directoryAudits
- Filters on time range via activityDateTime ge <timestamp>
- Filters on specific user input as observable, thanks to initiatedBy/user/userPrincipalName eq 'mail@observable.com'.

Required Permissions
- AuditLog.Read.All (Application permission)

Sample Usage

  • Run on TheHive’s observable of type mail
  • Analyzer fetches directory audit logs for that user over the last X days.

getManagedDevicesInfo (requires MS Intune)#

Purpose
Returns Intune-managed devices for a given user’s principal name or hostname, letting IR see device compliance, OS, last check-in, etc.

Key Points
- Graph Endpoint
- GET /deviceManagement/managedDevices
- Filters with startswith(userPrincipalName,'xxx') or an exact match (eq), with observable value.

Required Permissions
- DeviceManagementManagedDevices.Read.All (Application permission)

Sample Usage

  • Run on TheHive’s observable of type mail or hostname
  • Analyzer returns a list of Intune devices assigned to that user.

getDirectoryRoles#

Purpose
Lists the Microsoft Entra ID directory roles (built-in admin roles, such as Global Administrator, User Administrator...) directly assigned to a user, to help prioritize investigations involving privileged accounts.

Key Points
- Graph Endpoint
- GET /users/{id}/transitiveMemberOf/microsoft.graph.directoryRole
- Flags a curated list of highly-privileged built-in role names (Global Administrator, Privileged Role Administrator, Security Administrator, etc.) as suspicious in the taxonomy. - Limitation: only active/direct role assignments are returned. PIM-eligible roles that haven't been activated, and roles granted through a role-assignable group, aren't included.

Required Permissions
- Directory.Read.All (same permission already used by getUserInfo, no extra consent needed)

Sample Usage

  • Run on TheHive’s observable of type mail
  • Analyzer returns every directory role assigned to that user, and flags privileged ones.

getSignInsByIP#

Purpose
Pivots from a suspicious IP address observable to every Entra ID account that signed in from it, within the specified time range. Useful for spotting credential stuffing / password spray patterns (many distinct users, many failures, from the same IP).

Key Points
- Graph Endpoint
- GET /auditLogs/signIns
- Filters sign-ins tenant-wide by ipAddress eq 'x.x.x.x' and time range.

Required Permissions
- AuditLog.Read.All (Application permission, same as getSignIns)

Example Configuration

  • lookup_range = 7 (past 7 days)
  • lookup_limit = 50

Sample Usage

  • Run on TheHive’s observable of type ip
  • Analyzer returns every sign-in from that IP in the last 7 days, the number of distinct accounts involved, and flags risky/failed sign-ins.

getRiskyUser (requires Entra ID P1/P2)#

Purpose
Retrieves Microsoft Entra ID Identity Protection risk information for a user: their current aggregate risk state, and their risk detection history (impossible travel, leaked credentials, anonymous IP, etc.).

Key Points
- Graph Endpoints
- GET /identityProtection/riskyUsers/{id} current risk state. Requires Entra ID P2. - GET /identityProtection/riskDetections risk detection history, filtered by userId and time range. Requires Entra ID P1 or P2. - The two calls are independent: if the tenant/app isn't entitled or permissioned for one of them, that part of the report explains why (riskyUserError / riskDetectionsError) instead of failing the whole analyzer.

Required Permissions
- IdentityRiskyUser.Read.All (Application permission)
- IdentityRiskEvent.Read.All (Application permission)

Example Configuration

  • lookup_range = 30 (past 30 days of risk detections)
  • lookup_limit = 20

Sample Usage

  • Run on TheHive’s observable of type mail
  • Analyzer returns the user's current risk level/state and their recent risk detection history.

Customization#

Sign-Ins Table Color Coding#

In TheHive, the analyzer’s long report can be customized to highlight sign-ins with certain risk or unusual locations. For instance:

  • Yellow for out-of-state sign-ins
  • Red for foreign sign-ins

To do this, modify long.html for the analyzer (Sign In). For example, use ng-style or custom logic to check values in the JSON (like location.state or riskLevel). A sample snippet might be commented out at line 34 of long.html (if provided in your code), which you can adapt to your color preferences.

General Notes on Permissions#

  • Application (Client Credentials) Flow

    • These analyzers typically use .default scope and client credentials.
    • Ensure you Grant admin consent for the required permissions in Azure AD.

  • Minimal Scopes

    • If you want all analyzers to function, add each relevant scope (such as AuditLog.Read.All, Directory.Read.All, DeviceManagementManagedDevices.Read.All, UserAuthenticationMethod.Read.All, IdentityRiskyUser.Read.All, IdentityRiskEvent.Read.All) to the same app registration.
    • Alternatively, create separate app registrations to follow least-privilege principles.

  • Licensing

    • getRiskyUser requires Entra ID P2 (riskyUsers) and Entra ID P1 or P2 (riskDetections). Without the right license, Microsoft Graph returns an authorization error rather than an empty result, the analyzer reports this explicitly instead of failing outright.
    • Other features (such as advanced audit log retention) may also require Azure AD Premium licensing depending on your tenant configuration.

References#

MSEntraID_GetDirectoryRoles#

Author: 3lina, StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

List the Microsoft Entra ID directory roles (built-in admin roles) directly assigned to a user, to help prioritize investigations involving privileged accounts.

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetSignInsByIP#

Author: 3lina, StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- ip
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Pull all Microsoft Entra ID sign ins across the tenant that originated from a given IP address, within the specified amount of time.

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
lookup_range Check for sign ins in the last X days. Should be between 1 and 31 days.
Default value if not configured 7
Type of the configuration item number
The configuration item can contain multiple values False
Is required False
lookup_limit Display no more than this many sign ins.
Default value if not configured 50
Type of the configuration item number
The configuration item can contain multiple values False
Is required False

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetSignIns#

Author: @jahamilto
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Pull all Microsoft Entra ID sign ins for a user within the specified amount of time.

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
lookup_range Check for sign ins in the last X days. Should be between 1 and 31 days.
Default value if not configured 7
Type of the configuration item number
The configuration item can contain multiple values False
Is required False
lookup_limit Display no more than this many sign ins.
Default value if not configured 12
Type of the configuration item number
The configuration item can contain multiple values False
Is required False
state Expected sign in state (used as a taxonomy when sign ins appear outside of this area).
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required False
country Expected sign in country or region (used as a taxonomy when sign ins appear outside of this area).
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required False

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetDirectoryAuditLogs#

Author: Fabien Bloume, StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Pull Microsoft Entra ID directory audit logs for a user within the specified timeframe.

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
lookup_range Check for Directory Audit Logs in the last X days. Should be between 1 and 31 days.
Default value if not configured 7
Type of the configuration item number
The configuration item can contain multiple values False
Is required False
lookup_limit Display no more than this many Directory Audit Logs.
Default value if not configured 12
Type of the configuration item number
The configuration item can contain multiple values False
Is required False

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetRiskyUser#

Author: StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Retrieve Microsoft Entra ID Identity Protection risk information for a user: current risk state (riskyUsers) and risk detection history (riskDetections). Requires Entra ID P1/P2.

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
lookup_range Check for risk detections in the last X days. Should be between 1 and 90 days.
Default value if not configured 30
Type of the configuration item number
The configuration item can contain multiple values False
Is required False
lookup_limit Display no more than this many risk detections.
Default value if not configured 20
Type of the configuration item number
The configuration item can contain multiple values False
Is required False

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetUserInfo#

Author: Fabien Bloume, StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
- other
- user
- username
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Get information about the user from Microsoft Entra ID, using mail or user identifier (UPN/sAMAccountName/employeeId)

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
params_list list of query params to get User information
Default value if not configured ['businessPhones', 'givenName', 'surname', 'userPrincipalName', 'displayName', 'jobTitle', 'mail', 'mobilePhone', 'officeLocation', 'department', 'accountEnabled', 'onPremisesSyncEnabled', 'onPremisesLastSyncDateTime', 'onPremisesSecurityIdentifier', 'proxyAddresses', 'usageLocation', 'userType', 'createdDateTime']
Type of the configuration item string
The configuration item can contain multiple values True
Is required True
extended_search Search by additional fields (onPremisesSamAccountName, employeeId) in addition to UPN and mail
Default value if not configured True
Type of the configuration item boolean
The configuration item can contain multiple values False
Is required False

Templates samples for TheHive#

No template samples to display.

MSEntraID_GetManagedDevicesInfo#

Author: Fabien Bloume, StrangeBee
License: AGPL-V3
Version: 1.0
Supported observables types:
- mail
- hostname
Registration required: True
Subscription required: True
Free subscription: False
Third party service: https://www.microsoft.com/security/business/identity-access/microsoft-entra-id

Description#

Get Microsoft Intune Managed Device(s) Details from hostname or mail

Configuration#

tenant_id Microsoft Entra ID Tenant ID
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_id Client ID/Application ID of Microsoft Entra ID Registered App
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True
client_secret Secret for Microsoft Entra ID Registered Application
Default value if not configured N/A
Type of the configuration item string
The configuration item can contain multiple values False
Is required True

Templates samples for TheHive#

No template samples to display.